osbot-utils 2.33.0__py3-none-any.whl → 2.35.0__py3-none-any.whl

osbot_utils/helpers/llms/schemas/Schema__LLM_Request__Data.py

@@ -0,0 +1,14 @@
+from typing                                                                 import List, Optional
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Request__Function_Call    import Schema__LLM_Request__Function_Call
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Request__Message__Content import Schema__LLM_Request__Message__Content
+from osbot_utils.type_safe.Type_Safe                                        import Type_Safe
+
+class Schema__LLM_Request__Data(Type_Safe):                                         # Schema for LLM API request data
+    model         : str                                                             # LLM model identifier
+    platform      : str
+    provider      : str
+    messages      : List    [Schema__LLM_Request__Message__Content]                 # Message content entries
+    function_call : Optional[Schema__LLM_Request__Function_Call  ] = None           # Details of function call
+    temperature   : Optional[float                               ] = None           # Model temperature (0-1)
+    top_p         : Optional[float                               ] = None           # Nucleus sampling parameter
+    max_tokens    : Optional[int                                 ] = None           # Maximum tokens to generate

osbot_utils/helpers/llms/schemas/Schema__LLM_Request__Function_Call.py

@@ -0,0 +1,8 @@
+from typing                          import Type
+from osbot_utils.type_safe.Type_Safe import Type_Safe
+
+
+class Schema__LLM_Request__Function_Call(Type_Safe):
+    parameters    : Type[Type_Safe]                     # Class to generate schema from for function calling
+    function_name : str                                 # Name of the function to call
+    description   : str                                 # Description of the function

osbot_utils/helpers/llms/schemas/Schema__LLM_Request__Message__Content.py

@@ -0,0 +1,6 @@
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Request__Message__Role import Schema__LLM_Request__Message__Role
+from osbot_utils.type_safe.Type_Safe                                     import Type_Safe
+
+class Schema__LLM_Request__Message__Content(Type_Safe):                # Schema for message content in LLM requests.
+    role   : Schema__LLM_Request__Message__Role                       # Message role (system, user, assistant)
+    content: str                                                     # Message content

osbot_utils/helpers/llms/schemas/Schema__LLM_Request__Message__Role.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class Schema__LLM_Request__Message__Role(Enum):
+    ASSISTANT : str = 'assistant'
+    SYSTEM    : str = 'system'
+    USER      : str = 'user'
+
+

osbot_utils/helpers/llms/schemas/Schema__LLM_Response.py

@@ -0,0 +1,9 @@
+from osbot_utils.helpers.Obj_Id         import Obj_Id
+from osbot_utils.helpers.Timestamp_Now  import Timestamp_Now
+from osbot_utils.type_safe.Type_Safe    import Type_Safe
+
+
+class Schema__LLM_Response(Type_Safe):
+    response_id   : Obj_Id
+    timestamp     : Timestamp_Now
+    response_data : dict

osbot_utils/helpers/llms/schemas/Schema__LLM_Response__Cache.py

@@ -0,0 +1,13 @@
+from osbot_utils.helpers.Obj_Id                             import Obj_Id
+from osbot_utils.helpers.Timestamp_Now                      import Timestamp_Now
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Request   import Schema__LLM_Request
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Response  import Schema__LLM_Response
+from osbot_utils.helpers.safe_str.Safe_Str__Hash            import Safe_Str__Hash
+from osbot_utils.type_safe.Type_Safe                        import Type_Safe
+
+class Schema__LLM_Response__Cache(Type_Safe):
+    cache_id               : Obj_Id
+    hash__request          : Safe_Str__Hash       = None
+    llm_response           : Schema__LLM_Response = None
+    llm_request            : Schema__LLM_Request  = None
+    timestamp              : Timestamp_Now

osbot_utils/helpers/safe_str/Safe_Str.py

@@ -0,0 +1,50 @@
+import re
+from typing import Optional
+
+TYPE_SAFE__STR__REGEX__SAFE_STR = re.compile(r'[^a-zA-Z0-9]')    # Only allow alphanumerics and numbers
+TYPE_SAFE__STR__MAX_LENGTH      = 512
+
+class Safe_Str(str):
+    max_length                : int           = TYPE_SAFE__STR__MAX_LENGTH
+    regex                     : re.Pattern    = TYPE_SAFE__STR__REGEX__SAFE_STR
+    replacement_char          : str           = '_'
+    allow_empty               : bool          = True
+    trim_whitespace           : bool          = False
+    allow_all_replacement_char: bool          = True
+    strict_validation         : bool          = False               # If True, don't replace invalid chars, raise an error instead
+    exact_length              : bool          = False               # If True, require exact length match, not just max length
+
+
+    def __new__(cls, value: Optional[str] = None) -> 'Safe_Str':
+
+        if value is None:                                                                                               # Validate inputs
+            if cls.allow_empty:
+                value = ""
+            else:
+                raise ValueError("Value cannot be None when allow_empty is False")
+
+        if not isinstance(value, str):                                                                                  # Convert to string if not already
+            value = str(value)
+
+        if cls.trim_whitespace:                                                                                         # Trim whitespace if requested
+            value = value.strip()
+
+        if not cls.allow_empty and (value is None or value == ""):                                                      # Check for empty string if not allowed
+            raise ValueError("Value cannot be empty when allow_empty is False")
+
+        if cls.exact_length and len(value) != cls.max_length:
+            raise ValueError(f"Value must be exactly {cls.max_length} characters long (was {len(value)})")
+        elif not cls.exact_length and len(value) > cls.max_length:                                                      # Check max length
+            raise ValueError(f"Value exceeds maximum length of {cls.max_length} characters (was {len(value)})")
+
+        if cls.strict_validation:                                                                                       # If using strict validation, check if the value matches the regex pattern exactly
+            if not cls.regex.search(value) is None:                                                                     # If there are non-matching characters
+                raise ValueError(f"Value contains invalid characters (must match pattern: {cls.regex.pattern})")
+            sanitized_value = value
+        else:
+            sanitized_value = cls.regex.sub(cls.replacement_char, value)                                                    # Apply regex sanitization
+
+            if not cls.allow_all_replacement_char and set(sanitized_value) == {cls.replacement_char} and sanitized_value:   # Check if sanitized value consists entirely of replacement characters
+                raise ValueError(f"Sanitized value consists entirely of '{cls.replacement_char}' characters")
+
+        return str.__new__(cls, sanitized_value)

osbot_utils/helpers/safe_str/Safe_Str__File__Name.py

@@ -0,0 +1,8 @@
+import re
+from osbot_utils.helpers.safe_str.Safe_Str import Safe_Str
+
+class Safe_Str__File__Name(Safe_Str):
+    regex                      = re.compile(r'[^a-zA-Z0-9_\-. ]')
+    allow_empty                = False
+    trim_whitespace            = True
+    allow_all_replacement_char = False

osbot_utils/helpers/safe_str/Safe_Str__File__Path.py

@@ -0,0 +1,12 @@
+import re
+from osbot_utils.helpers.safe_str.Safe_Str import Safe_Str
+
+TYPE_SAFE_STR__FILE_PATH__REGEX      = re.compile(r'[^a-zA-Z0-9_\-./\\ ]')  # Allow alphanumerics, underscores, hyphens, dots, slashes, and spaces
+TYPE_SAFE_STR__FILE_PATH__MAX_LENGTH = 1024
+
+class Safe_Str__File__Path(Safe_Str):
+    regex                      = TYPE_SAFE_STR__FILE_PATH__REGEX
+    max_length                 = TYPE_SAFE_STR__FILE_PATH__MAX_LENGTH
+    allow_empty                = True
+    trim_whitespace            = True
+    allow_all_replacement_char = False

osbot_utils/helpers/safe_str/Safe_Str__Hash.py

@@ -0,0 +1,14 @@
+import re
+from osbot_utils.helpers.safe_str.Safe_Str import Safe_Str
+
+# Constants for hash validation
+SIZE__VALUE_HASH           = 10
+TYPE_SAFE_STR__HASH__REGEX = re.compile(r'[^a-fA-F0-9]')                # Only allow hexadecimal characters
+
+class Safe_Str__Hash(Safe_Str):
+    regex                     = TYPE_SAFE_STR__HASH__REGEX
+    max_length                = SIZE__VALUE_HASH
+    allow_empty               = False                                   # Don't allow empty hash values
+    trim_whitespace           = True                                    # Trim any whitespace
+    strict_validation         = True                                    # Enable strict validation - new attribute
+    exact_length              = True                                    # Require exact length match - new attribute

osbot_utils/helpers/safe_str/Safe_Str__Text.py

@@ -0,0 +1,9 @@
+import re
+from osbot_utils.helpers.safe_str.Safe_Str import Safe_Str
+
+TYPE_SAFE_STR__TEXT__MAX_LENGTH = 4096
+TYPE_SAFE_STR__TEXT__REGEX      = r'[^a-zA-Z0-9_ ()\[\]\-+=:;,.?]'
+
+class Safe_Str__Text(Safe_Str):
+    regex      = re.compile(TYPE_SAFE_STR__TEXT__REGEX)
+    max_length = TYPE_SAFE_STR__TEXT__MAX_LENGTH

osbot_utils/helpers/safe_str/Safe_Str__Text__Dangerous.py

@@ -0,0 +1,9 @@
+import re
+from osbot_utils.helpers.safe_str.Safe_Str import Safe_Str
+
+TYPE_SAFE_STR__TEXT__DANGEROUS__MAX_LENGTH = 65536
+TYPE_SAFE_STR__TEXT__DANGEROUS__REGEX      = r'[^a-zA-Z0-9_\s!@#$%^&*()\[\]{}\-+=:;,.?"/\\<>\']'
+
+class Safe_Str__Text__Dangerous(Safe_Str):
+    regex      = re.compile(TYPE_SAFE_STR__TEXT__DANGEROUS__REGEX)
+    max_length = TYPE_SAFE_STR__TEXT__DANGEROUS__MAX_LENGTH

osbot_utils/helpers/sqlite/Sqlite__Cursor.py

@@ -1,9 +1,7 @@
-from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
-from osbot_utils.decorators.methods.cache import cache
-from osbot_utils.decorators.methods.cache_on_self import cache_on_self
-from osbot_utils.helpers.sqlite.Sqlite__Database import Sqlite__Database
-from osbot_utils.utils.Status import status_ok, status_error, status_exception
-
+from osbot_utils.base_classes.Kwargs_To_Self        import Kwargs_To_Self
+from osbot_utils.decorators.methods.cache_on_self   import cache_on_self
+from osbot_utils.helpers.sqlite.Sqlite__Database    import Sqlite__Database
+from osbot_utils.utils.Status                       import status_ok, status_error, status_exception
 
 class Sqlite__Cursor(Kwargs_To_Self):
     database : Sqlite__Database

osbot_utils/helpers/sqlite/Sqlite__Database.py

@@ -1,4 +1,4 @@
-from osbot_utils.type_safe.Type_Safe             import Type_Safe
+from osbot_utils.type_safe.Type_Safe                import Type_Safe
 from osbot_utils.decorators.methods.cache_on_self   import cache_on_self
 from osbot_utils.utils.Files                        import current_temp_folder, path_combine, folder_create, file_exists, file_delete
 from osbot_utils.utils.Misc                         import  random_filename

osbot_utils/helpers/sqlite/Sqlite__Field.py

@@ -1,11 +1,6 @@
-import inspect
-import typing
-from decimal import Decimal
-from enum import auto, Enum
-from typing import Optional, Union
-
-from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
-from osbot_utils.helpers.sqlite.models.Sqlite__Field__Type import Sqlite__Field__Type
+from typing                                                 import Optional, Union
+from osbot_utils.base_classes.Kwargs_To_Self                import Kwargs_To_Self
+from osbot_utils.helpers.sqlite.models.Sqlite__Field__Type  import Sqlite__Field__Type
 
 
 class Sqlite__Field(Kwargs_To_Self):

osbot_utils/helpers/sqlite/Sqlite__Table.py

@@ -1,5 +1,4 @@
 import re
-
 from osbot_utils.base_classes.Kwargs_To_Self                import Kwargs_To_Self
 from osbot_utils.decorators.lists.filter_list               import filter_list
 from osbot_utils.decorators.lists.index_by                  import index_by
@@ -8,10 +7,9 @@ from osbot_utils.helpers.Print_Table                        import Print_Table
 from osbot_utils.helpers.sqlite.Sqlite__Database            import Sqlite__Database
 from osbot_utils.helpers.sqlite.Sqlite__Globals             import DEFAULT_FIELD_NAME__ID, ROW_BASE_CLASS, SQL_TABLE__MODULE_NAME__ROW_SCHEMA
 from osbot_utils.helpers.sqlite.models.Sqlite__Field__Type  import Sqlite__Field__Type
-from osbot_utils.utils.Dev import pprint
 from osbot_utils.utils.Json                                 import json_load
 from osbot_utils.utils.Misc                                 import list_set
-from osbot_utils.utils.Objects import base_types, default_value, bytes_to_obj, obj_to_bytes
+from osbot_utils.utils.Objects                              import base_types, default_value, bytes_to_obj, obj_to_bytes
 from osbot_utils.utils.Str                                  import str_cap_snake_case
 
 class Sqlite__Table(Kwargs_To_Self):

osbot_utils/helpers/sqlite/domains/Sqlite__DB__Files.py

@@ -1,7 +1,7 @@
 from osbot_utils.decorators.lists.index_by                  import index_by
 from osbot_utils.decorators.methods.cache_on_self           import cache_on_self
 from osbot_utils.helpers.sqlite.domains.Sqlite__DB__Local   import Sqlite__DB__Local
-
+from osbot_utils.utils.Json                                 import str_to_json
 
 
 class Sqlite__DB__Files(Sqlite__DB__Local):
@@ -21,9 +21,13 @@ class Sqlite__DB__Files(Sqlite__DB__Local):
     def file(self, path, include_contents=False):
         return self.table_files().file(path, include_contents=include_contents)
 
-    def file_contents(self, path):
+    def file_contents(self, path) -> str:
         return self.table_files().file_contents(path)
 
+    def file_contents__json(self, path) -> dict:
+        file_contents = self.file_contents(path)
+        return str_to_json(file_contents)
+
     def file__with_content(self, path):
         return self.file(path, include_contents=True)
 

osbot_utils/helpers/sqlite/models/Sqlite__Field__Type.py

@@ -1,7 +1,7 @@
 import sys
 import types
-from decimal import Decimal
-from enum import Enum, auto
+from decimal                              import Decimal
+from enum                                 import Enum, auto
 from osbot_utils.decorators.methods.cache import cache
 
 if sys.version_info >= (3, 10):

osbot_utils/helpers/sqlite/tables/Sqlite__Table__Files.py

@@ -1,12 +1,12 @@
-from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
+from osbot_utils.base_classes.Kwargs_To_Self  import Kwargs_To_Self
 from osbot_utils.helpers.sqlite.Sqlite__Table import Sqlite__Table
-from osbot_utils.utils.Misc import timestamp_utc_now, bytes_sha256, str_sha256
-from osbot_utils.utils.Status import status_warning, status_ok
+from osbot_utils.utils.Misc                   import timestamp_utc_now, bytes_sha256, str_sha256
+from osbot_utils.utils.Status                 import status_warning, status_ok
 
 SQLITE__TABLE_NAME__FILES = 'files'
 
 class Schema__Table__Files(Kwargs_To_Self):
-    path     : str
+    path     : str                              # todo: add support for using Safe_Str__File__Path (this will need changes to how Sqlite__Field__Type is mapped in add_field_with_type)
     contents : bytes
     metadata : bytes
     timestamp: int
@@ -50,7 +50,7 @@ class Sqlite__Table__Files(Sqlite__Table):
         return status_ok(message='file deleted')
 
     def create_node_data(self, path, contents=None, metadata= None):
-        node_data = {'path'    : path     ,
+        node_data = {'path'    : str(path),
                      'contents': contents ,
                      'metadata': metadata }
         if self.set_timestamp:

osbot_utils/helpers/ssh/SSH__Execute.py

@@ -2,7 +2,6 @@ from osbot_utils.type_safe.Type_Safe                            import Type_Safe
 from osbot_utils.helpers.duration.decorators.capture_duration   import capture_duration
 from osbot_utils.decorators.lists.group_by                      import group_by
 from osbot_utils.decorators.lists.index_by                      import index_by
-from osbot_utils.utils.Dev                                      import pprint
 from osbot_utils.utils.Env                                      import get_env
 from osbot_utils.utils.Http                                     import is_port_open
 from osbot_utils.utils.Misc                                     import str_to_int, str_to_bool

osbot_utils/helpers/ssh/SSH__Health_Check.py

@@ -1,8 +1,7 @@
-from osbot_utils.helpers.ssh.SSH__Execute import ENV_VAR__SSH__HOST, ENV_VAR__SSH__KEY_FILE, ENV_VAR__SSH__USER, \
-    ENV_VAR__SSH__PORT, ENV_VAR__SSH__STRICT_HOST_CHECK, SSH__Execute
-from osbot_utils.utils.Env import get_env
-from osbot_utils.utils.Misc import list_set
-from osbot_utils.utils.Status import status_ok, status_error
+from osbot_utils.helpers.ssh.SSH__Execute   import ENV_VAR__SSH__HOST, ENV_VAR__SSH__KEY_FILE, ENV_VAR__SSH__USER, ENV_VAR__SSH__PORT, ENV_VAR__SSH__STRICT_HOST_CHECK, SSH__Execute
+from osbot_utils.utils.Env                  import get_env
+from osbot_utils.utils.Misc                 import list_set
+from osbot_utils.utils.Status               import status_ok, status_error
 
 ENV_VARS__FOR_SSH = {'ssh_host'         : ENV_VAR__SSH__HOST              ,
                      'ssh_key_file'     : ENV_VAR__SSH__KEY_FILE          ,

osbot_utils/testing/performance/Performance_Measure__Session.py

@@ -122,7 +122,7 @@ class Performance_Measure__Session(Type_Safe):
         if self.assert_enabled is False:
             return
         if in_github_action():
-            max_time   = max_time * 5               # adjust for GitHub's slowness
+            max_time   = max_time * 6               # adjust for GitHub's slowness
 
         assert self.result.final_score <= max_time,  f"Performance changed for {self.result.name}: got {self.result.final_score:,d}ns, expected less than {max_time}ns"
 

osbot_utils/type_safe/Type_Safe__Base.py

@@ -1,3 +1,4 @@
+import types
 from typing                                         import get_args, Union, Optional, Any, ForwardRef
 from osbot_utils.helpers.Obj_Id                     import Obj_Id
 from osbot_utils.type_safe.shared.Type_Safe__Cache  import type_safe_cache
@@ -28,9 +29,9 @@ class Type_Safe__Base:
                     actual_type_name   = type_str(type(item))
                     raise TypeError(f"Expected '{expected_type_name}', but got '{actual_type_name}'")
 
-        elif origin is list and args:                                                    # Expected type is List[...]
+        elif origin in (list, set) and args:                                                    # Expected type is List[...]
             (item_type,) = args
-            if not isinstance(item, list):
+            if not isinstance(item, (list,set)):
                 expected_type_name = type_str(expected_type)
                 actual_type_name   = type_str(type(item))
                 raise TypeError(f"Expected '{expected_type_name}', but got '{actual_type_name}'")
@@ -81,6 +82,20 @@ class Type_Safe__Base:
             expected_type_name = type_str(expected_type)
             actual_type_name   = type_str(type(item))
             raise TypeError(f"Expected '{expected_type_name}', but got '{actual_type_name}'")
+        elif origin is type:                                            # Expected type is Type[T]
+            if type(item) is str:
+                item = deserialize_type__using_value(item)
+            if not isinstance(item, type):                              # First check if item is actually a type
+                expected_type_name = type_str(expected_type)
+                actual_type_name   = type_str(type(item))
+                raise TypeError(f"Expected {expected_type_name}, but got instance: {actual_type_name}")
+
+            args = get_args(expected_type)
+            if args:                                                    # Check if there are type arguments
+                type_arg = args[0]                                      # Then check if item is a subclass of T
+                if not issubclass(item, type_arg):
+                    raise TypeError(f"Expected subclass of {type_str(type_arg)}, got {type_str(item)}")
+            return True                                                 # If no args, any type is valid
         else:
             if isinstance(item, origin):
                 return True
@@ -103,4 +118,24 @@ def type_str(tp):
     else:
         args = get_args(tp)
         args_str = ', '.join(type_str(arg) for arg in args)
-        return f"{origin.__name__}[{args_str}]"
+        return f"{origin.__name__}[{args_str}]"
+
+# todo: this is duplicated from Type_Safe__Step__From_Json (review and figure out how to do this more centrally)
+def deserialize_type__using_value(value):         # TODO: Check the security implications of this deserialisation
+    from osbot_utils.type_safe.Type_Safe import Type_Safe
+    if value:
+        try:
+            module_name, type_name = value.rsplit('.', 1)
+            if module_name == 'builtins' and type_name == 'NoneType':                       # Special case for NoneType (which serialises as builtins.* , but it actually in types.* )
+                value = types.NoneType
+            else:
+                module = __import__(module_name, fromlist=[type_name])
+                value = getattr(module, type_name)
+                if isinstance(value, type) is False:
+                    raise ValueError(f"Security alert, in deserialize_type__using_value only classes are allowed")
+                # todo: figure out a way to do this
+                # if issubclass(value, (Type_Safe, str, int))  is False:
+                #     raise ValueError(f"Security alert, in deserialize_type__using_value only class of type Type_Safe, str, int are allowed")
+        except (ValueError, ImportError, AttributeError) as e:
+            raise ValueError(f"Could not reconstruct type from '{value}': {str(e)}")
+    return value

osbot_utils/type_safe/Type_Safe__Dict.py

@@ -1,5 +1,4 @@
-from typing import Type
-
+from typing                                import Type
 from osbot_utils.type_safe.Type_Safe__Base import Type_Safe__Base
 
 class Type_Safe__Dict(Type_Safe__Base, dict):
@@ -9,13 +8,8 @@ class Type_Safe__Dict(Type_Safe__Base, dict):
         self.expected_key_type   = expected_key_type
         self.expected_value_type = expected_value_type
 
-        # todo: see if we need to do this, since there was not code coverage hitting it
-        # for k, v in self.items():                           # check type-safety of ctor arguments
-        #     self.is_instance_of_type(k, self.expected_key_type  )
-        #     self.is_instance_of_type(v, self.expected_value_type)
-
     def __setitem__(self, key, value):                                  # Check type-safety before allowing assignment.
-        self.is_instance_of_type(key, self.expected_key_type)
+        self.is_instance_of_type(key  , self.expected_key_type)
         self.is_instance_of_type(value, self.expected_value_type)
         super().__setitem__(key, value)
 

osbot_utils/type_safe/Type_Safe__List.py

@@ -11,10 +11,14 @@ class Type_Safe__List(Type_Safe__Base, list):
         return f"list[{expected_type_name}] with {len(self)} elements"
 
     def append(self, item):
-        try:
-            self.is_instance_of_type(item, self.expected_type)
-        except TypeError as e:
-            raise TypeError(f"In Type_Safe__List: Invalid type for item: {e}")
+        from osbot_utils.type_safe.Type_Safe import Type_Safe
+        if type(self.expected_type) is type and issubclass(self.expected_type, Type_Safe) and type(item) is dict:  # if self.expected_type is Type_Safe and we have a dict
+            item = self.expected_type.from_json(item)  # try to convert the dict into self.expected_type
+        else:
+            try:
+                self.is_instance_of_type(item, self.expected_type)
+            except TypeError as e:
+               raise TypeError(f"In Type_Safe__List: Invalid type for item: {e}")
         super().append(item)
 
 

osbot_utils/type_safe/Type_Safe__Method.py

@@ -2,6 +2,8 @@ import inspect
 from enum       import Enum
 from typing     import get_args, get_origin, Union, List, Any, Dict                     # For type hinting utilities
 
+from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables import IMMUTABLE_TYPES
+
 
 class Type_Safe__Method:                                                                  # Class to handle method type safety validation
     def __init__(self, func):                                                             # Initialize with function
@@ -29,12 +31,23 @@ class Type_Safe__Method:
         return bound_args                                                                 # Return bound arguments
 
     def validate_parameter(self, param_name: str, param_value: Any, bound_args):          # Validate a single parameter
+        self.validate_immutable_parameter(param_name, param_value)                        # Validata the param_value (make sure if it set it is on of IMMUTABLE_TYPES)
         if param_name in self.annotations:                                                # Check if parameter is annotated
             expected_type = self.annotations[param_name]                                  # Get expected type
             self.check_parameter_value(param_name, param_value, expected_type, bound_args)# Check value against type
 
-    def check_parameter_value(self, param_name: str, param_value: Any,                    # Check parameter value against expected type
-                            expected_type: Any, bound_args):                              # Method parameters
+    def validate_immutable_parameter(self, param_name, param_value):
+        param = self.sig.parameters.get(param_name)      # Check if this is a default value from a mutable type
+        if param and param.default is param_value:       # This means the default value is being used
+            if param_value is not None:
+                if isinstance(param_value, IMMUTABLE_TYPES) is False:                            # Check if the value is an instance of any IMMUTABLE_TYPES
+                    raise ValueError(f"Parameter '{param_name}' has a mutable default value of type '{type(param_value).__name__}'. "
+                                     f"Only immutable types are allowed as default values in type_safe functions.")
+
+    def check_parameter_value(self, param_name   : str,
+                                    param_value  : Any,                    # Check parameter value against expected type
+                                    expected_type: Any,
+                                    bound_args       ):                              # Method parameters
         is_optional = self.is_optional_type(expected_type)                                # Check if type is optional
         has_default = self.has_default_value(param_name)                                  # Check if has default value
 
@@ -42,8 +55,23 @@ class Type_Safe__Method:
             self.validate_none_value(param_name, is_optional, has_default)                # Validate None value
             return                                                                        # Exit early
 
+        if is_optional:                                                                     # Extract the non-None type from Optional
+            non_none_type   = next(arg for arg in get_args(expected_type) if arg is not type(None))
+            non_none_origin = get_origin(non_none_type)
+
+            if non_none_origin is type:                                                     # If it's Optional[Type[T]], validate it
+                self.validate_type_parameter(param_name, param_value, non_none_type)
+                return
+            else:                                                                           # If it's any other Optional type, validate against the non-None type
+                self.check_parameter_value(param_name, param_value, non_none_type, bound_args)
+                return
+
         origin_type = get_origin(expected_type)                                           # Get base type
 
+        if origin_type is type:
+            self.validate_type_parameter(param_name, param_value, expected_type)
+            return
+
         if self.is_list_type(origin_type):                                               # Check if list type
             self.validate_list_type(param_name, param_value, expected_type)              # Validate list
             return                                                                       # Exit early
@@ -52,9 +80,9 @@ class Type_Safe__Method:
             self.validate_union_type(param_name, param_value, expected_type)             # Validate union
             return                                                                       # Exit early
 
-        if self.try_basic_type_conversion(param_value, expected_type, param_name,        # Try basic type conversion
-                                        bound_args):                                     # Pass bound args
-            return                                                                       # Exit if conversion successful
+        # if self.try_basic_type_conversion(param_value, expected_type, param_name,        # Try basic type conversion
+        #                                 bound_args):                                     # Pass bound args
+        #    return                                                                       # Exit if conversion successful
 
         self.validate_direct_type(param_name, param_value, expected_type)                # Direct type validation
 
@@ -85,6 +113,19 @@ class Type_Safe__Method:
             if not isinstance(item, item_type):                                       # Validate item type
                 raise ValueError(f"List item at index {i} expected type {item_type}, but got {type(item)}")  # Raise error for invalid item
 
+    def validate_type_parameter(self, param_name: str, param_value: Any, expected_type: Any):           # Validate a Type[T] parameter
+        if not isinstance(param_value, type):
+            raise ValueError(f"Parameter '{param_name}' expected a type class but got {type(param_value)}")
+
+
+        type_args = get_args(expected_type)                                                         # Extract the T from Type[T]
+        if type_args:
+            required_base = type_args[0]                                                            # get direct type (this doesn't handle Forward refs)
+            if hasattr(required_base, '__origin__') or isinstance(required_base, type):
+                if not issubclass(param_value, required_base):
+                    raise ValueError(f"Parameter '{param_name}' expected type {expected_type}, but got "
+                                     f"{param_value.__module__}.{param_value.__name__} which is not a subclass of {required_base}")
+
     def is_union_type(self, origin_type: Any, is_optional: bool) -> bool:             # Check if type is a Union
         return origin_type is Union and not is_optional                               # Must be Union but not Optional
 

osbot_utils/type_safe/Type_Safe__Tuple.py

@@ -8,7 +8,7 @@ class Type_Safe__Tuple(Type_Safe__Base, tuple):
         instance.expected_types = expected_types
         return instance
 
-    def __init__(self, expected_types, items=None):             # todo: see if we should be assining expected_types to self here
+    def __init__(self, expected_types, items=None):             # todo: see if we should be assigning expected_types to self here
         if items:
             self.validate_items(items)
 

osbot_utils/type_safe/shared/Type_Safe__Shared__Variables.py

@@ -1,8 +1,9 @@
 import types
 from enum import EnumMeta
 
-from osbot_utils.helpers.Safe_Id            import Safe_Id
+from osbot_utils.helpers.Safe_Id           import Safe_Id
+from osbot_utils.helpers.safe_str.Safe_Str import Safe_Str
 
 IMMUTABLE_TYPES = (bool, int, float, complex, str, bytes, types.NoneType, EnumMeta, type,
-                   Safe_Id          # ok to add since these classes use str as a base class
+                   #Safe_Id, Safe_Str             # ok to add since these classes use str as a base class # todo: see if we still need these
                    )

osbot_utils/type_safe/shared/Type_Safe__Validation.py

@@ -4,6 +4,7 @@ import types
 import typing
 from enum                                                           import EnumMeta
 from typing                                                         import Any, Annotated, Optional, get_args, get_origin, ForwardRef, Type, Dict, _GenericAlias
+from osbot_utils.helpers.safe_str.Safe_Str                          import Safe_Str
 from osbot_utils.type_safe.shared.Type_Safe__Annotations            import type_safe_annotations
 from osbot_utils.type_safe.shared.Type_Safe__Cache                  import type_safe_cache
 from osbot_utils.type_safe.shared.Type_Safe__Shared__Variables      import IMMUTABLE_TYPES
@@ -268,9 +269,9 @@ class Type_Safe__Validation:
         direct_type_match = type_safe_validation.check_if__type_matches__obj_annotation__for_attr(target, name, value)
         union_type_match  = type_safe_validation.check_if__type_matches__obj_annotation__for_union_and_annotated(target, name, value)
 
-        is_invalid = (direct_type_match is False and union_type_match is None) or \
-                    (direct_type_match is None and union_type_match is False) or \
-                    (direct_type_match is False and union_type_match is False)
+        is_invalid = (direct_type_match is False and union_type_match is None ) or \
+                     (direct_type_match is None  and union_type_match is False) or \
+                     (direct_type_match is False and union_type_match is False)
 
         if is_invalid:
             expected_type = annotations.get(name)
@@ -286,7 +287,8 @@ class Type_Safe__Validation:
             if self.obj_is_type_union_compatible(var_type, IMMUTABLE_TYPES) is False:                        # if var_type is not something like Optional[Union[int, str]]
                 if var_type not in IMMUTABLE_TYPES or type(var_type) not in IMMUTABLE_TYPES:
                     if not isinstance(var_type, EnumMeta):
-                        type_safe_raise_exception.immutable_type_error(var_name, var_type)
+                        if not issubclass(var_type, str):
+                            type_safe_raise_exception.immutable_type_error(var_name, var_type)
 
     def validate_variable_type(self, var_name, var_type, var_value):                                # Validate type compatibility
         if type(var_type) is type and not isinstance(var_value, var_type):

osbot_utils/type_safe/steps/Type_Safe__Step__Default_Value.py

@@ -1,8 +1,6 @@
-
 import sys
 import inspect
 import typing
-
 from osbot_utils.type_safe.Type_Safe__Set           import Type_Safe__Set
 from osbot_utils.type_safe.Type_Safe__Tuple         import Type_Safe__Tuple
 from osbot_utils.type_safe.shared.Type_Safe__Cache  import type_safe_cache