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

osbot_utils/helpers/Local_Cache.py

@@ -1,10 +1,8 @@
-from osbot_utils.utils.Misc import list_set
-from osbot_utils.utils.Dev import pprint
-from osbot_utils.decorators.methods.cache_on_self import cache_on_self
-from osbot_utils.utils.Files import current_temp_folder, path_combine, create_folder, safe_file_name, file_exists, \
-    file_delete, file_size
-from osbot_utils.utils.Json import json_save_file, json_load_file
-
+from osbot_utils.utils.Misc                         import list_set
+from osbot_utils.utils.Dev                          import pprint
+from osbot_utils.decorators.methods.cache_on_self   import cache_on_self
+from osbot_utils.utils.Files                        import current_temp_folder, path_combine, create_folder, safe_file_name, file_exists, file_delete, file_size
+from osbot_utils.utils.Json                         import json_save_file, json_load_file
 
 class Local_Cache:
 

osbot_utils/helpers/Local_Caches.py

@@ -1,8 +1,8 @@
-from pathlib import Path
-from typing import Dict, List
-from osbot_utils.helpers.Local_Cache import Local_Cache
-from osbot_utils.utils.Files import current_temp_folder, path_combine, folder_exists, folder_delete, file_extension
-from osbot_utils.utils.Misc          import random_text
+from pathlib                            import Path
+from typing                             import Dict, List
+from osbot_utils.helpers.Local_Cache    import Local_Cache
+from osbot_utils.utils.Files            import current_temp_folder, path_combine, folder_exists, folder_delete, file_extension
+from osbot_utils.utils.Misc             import random_text
 
 
 class Local_Caches:

osbot_utils/helpers/llms/actions/LLM_Request__Execute.py

@@ -0,0 +1,31 @@
+from osbot_utils.helpers.llms.cache.LLM_Request__Cache              import LLM_Request__Cache
+from osbot_utils.helpers.llms.builders.LLM_Request__Builder         import LLM_Request__Builder
+from osbot_utils.helpers.llms.platforms.open_ai.API__LLM__Open_AI   import API__LLM__Open_AI
+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.type_safe.Type_Safe                                import Type_Safe
+from osbot_utils.type_safe.decorators.type_safe                     import type_safe
+
+class LLM_Request__Execute(Type_Safe):
+    llm_cache      : LLM_Request__Cache
+    llm_api        : API__LLM__Open_AI
+    use_cache      : bool = True
+    request_builder: LLM_Request__Builder
+
+    @type_safe
+    def execute(self, llm_request: Schema__LLM_Request) -> Schema__LLM_Response:
+
+        if self.use_cache:                                                                          # Check cache if enabled
+            cached_response = self.llm_cache.get(llm_request)
+            if cached_response:
+                return cached_response
+
+        self.request_builder.llm_request_data = llm_request.request_data
+        llm_payload                           = self.request_builder.build_request_payload()
+        response_data                         = self.llm_api.execute(llm_payload)                   # Make API call
+        llm_response                          = Schema__LLM_Response(response_data=response_data)   # Create response object
+
+        if self.use_cache:                                                                          # Cache the response if enabled
+            self.llm_cache.add(llm_request, llm_response)
+
+        return llm_response

osbot_utils/helpers/llms/actions/Type_Safe__Schema_For__LLMs.py

@@ -0,0 +1,213 @@
+import re
+from typing                                                     import Type, Any, List, Dict, Tuple, Set, Optional, Union, get_origin, get_args
+from osbot_utils.type_safe.Type_Safe                            import Type_Safe
+from osbot_utils.type_safe.decorators.type_safe                 import type_safe
+from osbot_utils.type_safe.shared.Type_Safe__Cache              import type_safe_cache
+from osbot_utils.type_safe.validators.Type_Safe__Validator      import Type_Safe__Validator
+from osbot_utils.type_safe.validators.Validator__Min            import Validator__Min
+from osbot_utils.type_safe.validators.Validator__Max            import Validator__Max
+from osbot_utils.type_safe.validators.Validator__Regex          import Validator__Regex
+from osbot_utils.type_safe.validators.Validator__One_Of         import Validator__One_Of
+from osbot_utils.helpers.python_compatibility.python_3_8        import Annotated
+import inspect
+
+
+class Type_Safe__Schema_For__LLMs(Type_Safe):
+
+    @type_safe
+    def export(self, target : Type[Type_Safe]) -> dict:                                 # Target Type_Safe class to convert, Returns JSON Schema object
+        return self.export__type_safe(target)
+
+    def export__type_safe(self, target: Type[Type_Safe]) -> dict:                       # Target Type_Safe class to convert, Returns JSON Schema object
+        annotations = type_safe_cache.get_class_annotations(target)
+        properties  = {}
+        required    = []
+
+        schema = { "type"      : "object"   ,
+                   "properties": properties }
+
+        if target.__doc__:                                                              # Add description if available and requested
+            schema["description"] = self.clean_docstring(target.__doc__)
+
+        for var_name, var_type in annotations:                                          # Process all annotated fields
+
+            prop_schema          = self.get_property_schema(target, var_name, var_type)
+            properties[var_name] = prop_schema
+
+            if self.is_required_property(target, var_name, var_type):                # Check if property is required
+                required.append(var_name)
+
+        if required:                                                                  # Add required fields if any
+            schema["required"] = required
+
+        return schema
+
+    def clean_docstring(self, docstring: str) -> str:                                   # Cleans up a docstring
+        if not docstring:
+            return ""
+        lines = docstring.splitlines()
+
+        while lines and not lines[0].strip():                                           # Remove empty lines at the beginning
+            lines.pop(0)
+
+        while lines and not lines[-1].strip():                                          # Remove empty lines at the end
+            lines.pop()
+
+        indent = min((len(line) - len(line.lstrip())                                    # Find minimum indentation
+                     for line in lines if line.strip()), default=0)
+
+        return '\n'.join(line[indent:] for line in lines)                               # Remove indentation and join lines
+
+    def get_property_schema(self, target_cls : Type ,                                   # Class containing the property
+                                  var_name   : str  ,                                   # Name of the property
+                                  var_type   : Any  ,                                   # Type annotation of the property
+                               ) -> dict:                                               # Returns JSON Schema for property
+        validators = []
+        origin     = get_origin(var_type)
+
+        if origin is Annotated:                                                         # Handle Annotated types
+            args        = get_args(var_type)
+            base_type   = args[0]
+            validators  = [arg for arg in args[1:] if isinstance(arg, Type_Safe__Validator)]
+            var_type    = base_type
+            origin      = get_origin(base_type)         # todo: see if we need this field (which is not being used at the moment)
+
+        schema = self.get_type_schema(var_type)                                         # Get basic type schema
+
+        #if target_cls.__doc__:                                                          # Add description if available
+        doc = self.get_attribute_doc(target_cls, var_name)
+        if doc:
+            schema["description"] = doc
+
+        for validator in validators:                                                    # Apply validators
+            self._apply_validator(schema, validator)
+
+        return schema
+
+    def get_attribute_doc(self, cls     : Type ,                                        # Class to extract docs from
+                                attr_name: str
+                           ) -> Optional[str]:                                           # Returns attribute documentation
+        if cls.__doc__:                                                                  # Try class docstring first
+            lines = cls.__doc__.splitlines()
+            for i, line in enumerate(lines):
+                if f"{attr_name}:" in line or f"{attr_name} :" in line:
+                    parts = line.split(":", 1)
+                    if len(parts) > 1:
+                        return parts[1].strip()
+                    if i + 1 < len(lines) and lines[i + 1].strip():
+                        return lines[i + 1].strip()
+
+        try:                                                                            # if nor available Try source code comments next
+            source = inspect.getsource(cls)
+            lines  = source.splitlines()
+            for line in lines:
+                normal_case  = f"{attr_name}:" in line or f"{attr_name} :" in line       # Handle the normal case and the aligned case with variable spacing
+                aligned_case = re.search(fr"\b{attr_name}\s*:", line)
+
+                if normal_case or aligned_case:
+                    if "#" in line:
+                        return line.split("#", 1)[1].strip()
+                if f"{attr_name} :" in line or f"{attr_name}:" in line:
+                    if "#" in line:
+                        return line.split("#", 1)[1].strip()
+        except (TypeError, OSError):
+            pass
+
+        return None
+
+    def get_type_schema(self, type_hint: Any) -> dict:                                  # Convert Python type to JSON Schema
+        origin = get_origin(type_hint)
+
+        if   type_hint is str       : return {"type": "string"  }                       # Handle primitive types
+        elif type_hint is int       : return {"type": "integer" }
+        elif type_hint is float     : return {"type": "number"  }
+        elif type_hint is bool      : return {"type": "boolean" }
+        elif type_hint is None      : return {"type": "null"    }
+        elif type_hint is type(None): return {"type": "null"    }
+
+
+        if origin in (list, List):                                                      # Handle container types
+            args      = get_args(type_hint)
+            item_type = args[0] if args else Any
+            return { "type" : "array",
+                     "items": self.get_type_schema(item_type) }
+        elif origin in (dict, Dict):
+            args = get_args(type_hint)
+            if len(args) >= 2:
+                key_type, value_type = args[0], args[1]
+                return { "type"                : "object",
+                         "additionalProperties": self.get_type_schema(value_type) }
+            else:
+                return {"type": "object"}
+        elif origin in (tuple, Tuple):
+            args = get_args(type_hint)
+            if args:
+                return { "type"    : "array"                                    ,
+                         "items"   : [self.get_type_schema(arg) for arg in args],
+                         "minItems": len(args)                                  ,
+                         "maxItems": len(args)                                  }
+            else:
+                return {"type": "array"}
+        elif origin in (set, Set):
+            args = get_args(type_hint)
+            item_type = args[0] if args else Any
+            return { "type"       : "array"                         ,
+                     "items"      : self.get_type_schema(item_type) ,
+                     "uniqueItems": True                            }
+
+        elif origin is Union:                                                       # Handle union types (Optional is Union[type, None])
+            args = get_args(type_hint)
+            if len(args) == 2 and type(None) in args:
+                non_none_type = next(arg for arg in args if arg is not type(None))
+                schema = self.get_type_schema(non_none_type)
+                if "type" in schema and isinstance(schema["type"], str):
+                    schema["type"] = [schema["type"], "null"]
+                return schema
+            else:
+                return { "anyOf": [self.get_type_schema(arg) for arg in args] }
+
+
+        elif inspect.isclass(type_hint) and issubclass(type_hint, Type_Safe):       # Handle custom Type_Safe classes (nested objects)
+            return self.export__type_safe(type_hint)                                # Recursive call for nested objects
+
+        return {"type": "object"}                                                   # Default fallback
+
+    def _apply_validator(self, schema   : dict               ,                      # Schema to modify
+                               validator: Type_Safe__Validator
+                          ) -> None:                                                # Applies validator constraints
+        if isinstance(validator, Validator__Min):
+            if   schema.get("type") in ["integer", "number"]: schema["minimum"  ] = validator.min_value
+            elif schema.get("type") == "string"             : schema["minLength"] = validator.min_value
+            elif schema.get("type") == "array"              : schema["minItems" ] = validator.min_value
+
+        elif isinstance(validator, Validator__Max):
+            if   schema.get("type") in ["integer", "number"]: schema["maximum"  ] = validator.max_value
+            elif schema.get("type") == "string"             : schema["maxLength"] = validator.max_value
+            elif schema.get("type") == "array"              : schema["maxItems" ] = validator.max_value
+
+        elif isinstance(validator, Validator__Regex):
+            if schema.get("type") == "string":
+                schema["pattern"] = validator.pattern
+                if validator.description:
+                    if "description" not in schema:
+                        schema["description"] = validator.description
+                    else:
+                        schema["description"] += f" (Pattern: {validator.description})"
+
+        elif isinstance(validator, Validator__One_Of):
+            schema["enum"] = validator.allowed
+
+    def is_required_property(self, target_cls: Type ,                                   # Class containing the property
+                                   var_name  : str  ,                                   # Name of the property
+                                   var_type  : Any
+                              ) -> bool:                                                # Returns True if property is required
+        origin = get_origin(var_type)                                                   # Check if the type is Optional
+        if origin is Union:
+            args = get_args(var_type)
+            if type(None) in args:
+                return False
+
+        if hasattr(target_cls, var_name):                                               # Check if there's a default value in the class
+            return getattr(target_cls, var_name) is None
+
+        return True                                                                     # By default, consider it required

osbot_utils/helpers/llms/builders/LLM_Request__Builder.py

@@ -0,0 +1,41 @@
+from typing                                                                 import Dict, Any, Type
+from osbot_utils.helpers.llms.actions.Type_Safe__Schema_For__LLMs           import Type_Safe__Schema_For__LLMs
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Request__Data             import Schema__LLM_Request__Data
+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.helpers.llms.schemas.Schema__LLM_Request__Message__Role    import Schema__LLM_Request__Message__Role
+from osbot_utils.type_safe.Type_Safe                                        import Type_Safe
+from osbot_utils.type_safe.decorators.type_safe                             import type_safe
+
+class LLM_Request__Builder(Type_Safe):
+    schema_generator : Type_Safe__Schema_For__LLMs
+    llm_request_data : Schema__LLM_Request__Data
+
+    @type_safe
+    def add_message(self, role    : Schema__LLM_Request__Message__Role,
+                          content : str = None
+                     ) -> Schema__LLM_Request__Message__Content:
+        if content:
+            message = Schema__LLM_Request__Message__Content(role=role, content=content)
+            self.llm_request_data.messages.append(message)
+        return self
+
+    def add_message__assistant(self, content : str = None): return self.add_message(role=Schema__LLM_Request__Message__Role.ASSISTANT, content=content)
+    def add_message__system   (self, content : str = None): return self.add_message(role=Schema__LLM_Request__Message__Role.SYSTEM   , content=content)
+    def add_message__user     (self, content : str = None): return self.add_message(role=Schema__LLM_Request__Message__Role.USER     , content=content)
+
+    @type_safe
+    def set_function_call(self, parameters    : Type[Type_Safe],
+                                   function_name : str,
+                                   description   : str   = ''
+                           ) -> Schema__LLM_Request__Function_Call:
+        function_call = Schema__LLM_Request__Function_Call(parameters   = parameters,
+                                                          function_name = function_name,
+                                                          description   = description)
+        self.llm_request_data.function_call = function_call
+        return self
+
+
+    @type_safe
+    def build_request_payload(self) -> Dict[str, Any]:
+        raise NotImplementedError("Subclasses must implement this method")

osbot_utils/helpers/llms/builders/LLM_Request__Builder__Open_AI.py

@@ -0,0 +1,54 @@
+from typing                                                     import Dict, Any
+from osbot_utils.helpers.llms.builders.LLM_Request__Builder     import LLM_Request__Builder
+from osbot_utils.type_safe.decorators.type_safe                 import type_safe
+
+class LLM_Request__Builder__Open_AI(LLM_Request__Builder):
+
+    @type_safe
+    def build_request_payload(self) -> Dict[str, Any]:
+        payload = { "model"          : self.llm_request_data.model                                                             ,
+                    "messages"       : [{"role"  : msg.role.value, "content": msg.content} for msg in self.llm_request_data.messages]}
+        if self.llm_request_data.function_call:
+            schema = self.schema_generator.export(self.llm_request_data.function_call.parameters)
+            schema["additionalProperties"] = False                                  # needs to be False when using structured outputs
+            payload["response_format"    ] =  { "type"       : "json_schema",
+                                                "json_schema": { "name"  : self.llm_request_data.function_call.function_name,
+                                                                 "schema": schema                                      ,
+                                                                 'strict': True                                        }}
+
+        if self.llm_request_data.temperature is not None: payload["temperature"] = self.llm_request_data.temperature
+        if self.llm_request_data.top_p       is not None: payload["top_p"] = self.llm_request_data.top_p
+        if self.llm_request_data.max_tokens  is not None: payload["max_tokens"] = self.llm_request_data.max_tokens
+
+        return payload
+
+    # @type_safe
+    # def build_request_with_json_mode(self, request: Schema__LLM_Request
+    #                                 ) -> Dict[str, Any]:
+    #     """
+    #     Builds request using OpenAI's JSON mode rather than function calling.
+    #     This is an alternative approach for structured outputs that doesn't use the tools API.
+    #     """
+    #     payload = {
+    #         "model": request.model,
+    #         "messages": [
+    #             {"role": msg.role, "content": msg.content}
+    #             for msg in request.messages
+    #         ],
+    #         "response_format": {"type": "json_object"}
+    #     }
+    #
+    #     if request.temperature is not None:
+    #         payload["temperature"] = request.temperature
+    #     if request.top_p is not None:
+    #         payload["top_p"] = request.top_p
+    #     if request.max_tokens is not None:
+    #         payload["max_tokens"] = request.max_tokens
+    #
+    #     return payload
+
+    # @type_safe
+    # def build_request_json(self, request: Schema__LLM_Request
+    #                       ) -> str:
+    #     payload = self.build_request_payload(request)
+    #     return json_dumps(payload)

osbot_utils/helpers/llms/builders/LLM_Request__Factory.py

@@ -0,0 +1,95 @@
+from typing                                                     import Type, Optional, Dict, Any
+from osbot_utils.helpers.llms.builders.LLM_Request__Builder     import LLM_Request__Builder
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Request__Data import Schema__LLM_Request__Data
+from osbot_utils.type_safe.Type_Safe                            import Type_Safe
+from osbot_utils.type_safe.decorators.type_safe                 import type_safe
+
+
+class LLM_Request__Factory(Type_Safe):                              # Factory class for creating common LLM request patterns.
+    request_builder : LLM_Request__Builder
+
+    @type_safe
+    def create_simple_chat_request(self, model        : str                  ,          # Model identifier
+                                         provider     : str                  ,          # Provider name (openai, anthropic)
+                                         platform     : str                  ,          # Platform name
+                                         user_message : str                  ,          # User message content
+                                         system_prompt: Optional[str  ] = None ,          # Optional system prompt
+                                         temperature  : Optional[float] = None          # Temperature
+                                   )  -> Schema__LLM_Request__Data:                     # Create a simple chat request with optional system prompt.
+
+        with self.request_builder as _:
+            _.llm_request_data.model       = model
+            _.llm_request_data.provider    = provider
+            _.llm_request_data.platform    = platform
+            _.llm_request_data.temperature = temperature
+
+            _.add_message__system(content=system_prompt)                                # Add system prompt
+            _.add_message__user  (content=user_message )                                # Add user message
+        return self
+
+    @type_safe
+    def create_function_calling_request(self, model          : str                  ,          # Model identifier
+                                              provider       : str                  ,          # Provider name (openai, anthropic)
+                                              platform       : str                  ,          # Platform name
+                                              parameters     : Type[Type_Safe]      ,          # Parameters schema class
+                                              function_name  : str                  ,          # Function name
+                                              function_desc  : str                  ,          # Function description
+                                              user_message   : str                  ,          # User message
+                                              system_prompt  : Optional[str] = None ,          # Optional system prompt
+                                              temperature    : Optional[float] = None          # Temperature
+                                         ) -> Schema__LLM_Request__Data:                       # Create a request that uses function calling with the specified schema.
+
+        with self.request_builder as _:
+            _.set_function_call(parameters    = parameters   ,   # Create the function call
+                                function_name = function_name,
+                                description   = function_desc)
+
+            _.add_message__system(content=system_prompt)
+            _.add_message__user  (content=user_message )
+            _.llm_request_data.model       = model
+            _.llm_request_data.provider    = provider
+            _.llm_request_data.platform    = platform
+            _.llm_request_data.temperature = temperature
+        return self
+
+    @type_safe
+    def create_entity_extraction_request(self, model             : str                  ,          # Model identifier
+                                               provider          : str                  ,          # Provider name
+                                               platform          : str                  ,          # Platform name
+                                               entity_class      : Type[Type_Safe]      ,          # Entity schema class
+                                               text_to_analyze   : str                  ,          # Text to extract entities from
+                                               system_instruction: Optional[str] = None ,          # Optional system instructions
+                                               function_name     : str = "extract_entities",       # Function name
+                                               temperature       : Optional[float] = 0.2          # Low temperature for precision
+                                        )                        -> Schema__LLM_Request__Data:
+        """Create a specialized request for entity extraction using the provided schema."""
+        # Default system instruction if none provided
+        if system_instruction is None:
+            system_instruction = (
+                "You are an expert at analyzing text and extracting structured information. "
+                "Extract entities mentioned in the text according to the specified schema. "
+                "Be precise and only include information explicitly mentioned in the text."
+            )
+
+        # User message prompting for extraction
+        user_message = f"Extract key entities from this text: {text_to_analyze}"
+
+        # Create the function calling request
+        return self.create_function_calling_request(
+            model=model,
+            provider=provider,
+            platform=platform,
+            parameters=entity_class,
+            function_name=function_name,
+            function_desc="Extract entities from text",
+            system_prompt=system_instruction,
+            user_message=user_message,
+            temperature=temperature
+        )
+
+    def request_data(self) -> Schema__LLM_Request__Data:
+        return self.request_builder.llm_request_data
+
+    @type_safe
+    def build_request_payload(self) -> Dict[str, Any]:                     # Build a provider-specific request payload from a Schema__LLM_Request.
+        return self.request_builder.build_request_payload()

osbot_utils/helpers/llms/cache/LLM_Cache__Path_Generator.py

@@ -0,0 +1,83 @@
+from datetime                                           import datetime
+from typing                                             import List, Optional
+from osbot_utils.helpers.Safe_Id                        import Safe_Id
+from osbot_utils.helpers.safe_str.Safe_Str__File__Path  import Safe_Str__File__Path
+from osbot_utils.type_safe.Type_Safe                    import Type_Safe
+from osbot_utils.type_safe.decorators.type_safe         import type_safe
+
+class LLM_Cache__Path_Generator(Type_Safe):
+    @type_safe
+    def generate_path(self, year     : Optional[int] = None,        # Time components - all optional and independent
+                            month    : Optional[int] = None,
+                            day      : Optional[int] = None,
+                            hour     : Optional[int] = None,
+                            domains  : List[Safe_Id] = None,        # Before time path
+                            areas    : List[Safe_Id] = None,        # After time path
+                            file_id  : Safe_Id       = None,        # File components
+                            extension: str           = None
+                       ) -> Safe_Str__File__Path:                               # Generate a flexible path with optional time components and organizational elements."""
+
+        path = ""
+        if domains:                                                             # Build domains part (if any)
+            path += '/'.join(str(domain) for domain in domains)
+
+
+        time_parts = []                                                         # Build time path with any available components - fully independent
+        if year is not None:
+            time_parts.append(f'{year:04}')
+        if month is not None:
+            time_parts.append(f'{month:02}')
+        if day is not None:
+            time_parts.append(f'{day:02}')
+        if hour is not None:
+            time_parts.append(f'{hour:02}')
+
+        if time_parts:                                                          # Add timeparts (if any)
+            if path:
+                path += '/' + '/'.join(time_parts)
+            else:
+                path = '/'.join(time_parts)
+
+        if areas:                                                               # Add areas (if any)
+            if path:
+                path += '/' + '/'.join(str(area) for area in areas)
+            else:
+                path = '/'.join(str(area) for area in areas)
+
+        if file_id and extension:                                               # Add file ID and extension (if any)
+            if path:
+                path += f'/{file_id}.{extension}'
+            else:
+                path = f'{file_id}.{extension}'
+
+        return Safe_Str__File__Path(path)
+
+    @type_safe
+    def from_date_time(self, date_time  : datetime            ,
+                             domains    : List[Safe_Id] = None,
+                             areas      : List[Safe_Id] = None,
+                             file_id    : Safe_Id       = None,
+                             extension  : str           = None
+                        ) -> Safe_Str__File__Path:                              # Generate a path from a datetime object.
+        return self.generate_path(year      = date_time.year ,
+                                  month     = date_time.month,
+                                  day       = date_time.day  ,
+                                  hour      = date_time.hour ,
+                                  domains   = domains        ,
+                                  areas     = areas          ,
+                                  file_id   = file_id        ,
+                                  extension = extension      )
+
+    @type_safe
+    def now(self, domains   : List[Safe_Id] = None,
+                  areas     : List[Safe_Id] = None,
+                  file_id   : Safe_Id       = None,
+                  extension : str           = None,
+                  now       : datetime      = None
+             ) -> Safe_Str__File__Path:                                  # Generate a path using current time or provided timestamp.
+        date_time = now or datetime.now()
+        return self.from_date_time(date_time = date_time,
+                                   domains   = domains  ,
+                                   areas     = areas    ,
+                                   file_id   = file_id  ,
+                                   extension = extension)