osbot-utils 2.32.0__py3-none-any.whl → 2.34.0__py3-none-any.whl

osbot_utils/helpers/llms/cache/LLM_Request__Cache.py

@@ -0,0 +1,112 @@
+from typing                                                         import Dict, Optional, List
+from osbot_utils.helpers.Obj_Id                                     import Obj_Id
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Cache__Index      import Schema__LLM_Cache__Index
+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.llms.schemas.Schema__LLM_Response__Cache   import Schema__LLM_Response__Cache
+from osbot_utils.helpers.safe_str.Safe_Str__Hash                    import Safe_Str__Hash
+from osbot_utils.type_safe.Type_Safe                                import Type_Safe
+from osbot_utils.type_safe.decorators.type_safe                     import type_safe
+from osbot_utils.utils.Json                                         import json_md5
+
+SIZE__VALUE_HASH = 10
+
+class LLM_Request__Cache(Type_Safe):
+    cache_index      : Schema__LLM_Cache__Index                                             # Index mapping request hashes to cache entries
+    cache_entries    : Dict[Obj_Id, Schema__LLM_Response__Cache]                            # In-memory storage of cache entries
+
+    def save(self) -> bool:                                                                 # For overriding in subclasses
+        return True
+
+    @type_safe
+    def compute_request_hash(self, request: Schema__LLM_Request) -> Safe_Str__Hash:         # Computes hash for full request
+        request_json = request.request_data.json()
+        hash_value   = json_md5(request_json)[:SIZE__VALUE_HASH]
+        return Safe_Str__Hash(hash_value)
+
+    @type_safe
+    def add(self, request     : Schema__LLM_Request ,                                       # Request to cache
+                  response    : Schema__LLM_Response                                        # Response to store
+             ) -> Obj_Id:                                                                   # returns cache_id
+
+        hash_request          = self.compute_request_hash (request)                         # calculate request hash
+        cache_entry           = Schema__LLM_Response__Cache(cache_id                = Obj_Id()             ,              # Create a cache entry
+                                                            llm_request             = request              ,
+                                                            llm_response            = response             ,
+                                                            hash__request           = hash_request         )
+        cache_id             = cache_entry.cache_id
+
+        self.cache_index.cache_id__from__hash__request          [ hash_request         ] = cache_id                                      # Update the cache index
+        self.cache_entries                                       [cache_id             ] = cache_entry                                   # Store in memory
+
+        return cache_id
+
+    def get(self, request: Schema__LLM_Request) -> Optional[Schema__LLM_Response]:                                      # Cached response or None
+        request_hash = self.compute_request_hash(request)
+
+        if request_hash in self.cache_index.cache_id__from__hash__request:                                                              # Check if we have an exact match
+            cache_id    = self.cache_index.cache_id__from__hash__request[request_hash]
+            cache_entry = self.get_cache_entry(cache_id)
+            if cache_entry:
+                return cache_entry.llm_response
+
+        return None
+
+    @type_safe
+    def get_cache_entry(self, cache_id: Obj_Id) -> Optional[Schema__LLM_Response__Cache]:                               # Get cache entry by ID
+        return self.cache_entries.get(cache_id)
+
+    def exists(self, request: Schema__LLM_Request) -> bool:                                                             # True if in cache
+        request_hash = self.compute_request_hash(request)
+        return request_hash in self.cache_index.cache_id__from__hash__request
+
+    def delete(self, request : Schema__LLM_Request) -> bool:                                                            # Success status
+        request_hash  = self.compute_request_hash(request)
+
+        if request_hash not in self.cache_index.cache_id__from__hash__request:
+            return False
+
+        cache_id = self.cache_index.cache_id__from__hash__request[request_hash]
+
+        del self.cache_index.cache_id__from__hash__request[request_hash]                                                                # Remove from hashes
+
+        if cache_id in self.cache_entries:                                                                              # Remove from memory
+            del self.cache_entries[cache_id]
+
+        return self.save()
+
+    def get_by_id(self, cache_id : Obj_Id)-> Optional[Schema__LLM_Response]:                                            # Cached response or None
+        cache_entry = self.get_cache_entry(cache_id)
+        if cache_entry:
+            return cache_entry.llm_response
+        return None
+
+    def clear(self) -> bool:                                                                                            # Clear all cache entries
+        self.cache_index    = Schema__LLM_Cache__Index()
+        self.cache_entries  = {}
+        return self.save()
+
+    def stats(self) -> Dict:                                                                                            # Cache statistics
+
+        total_entries    = len(self.cache_index.cache_id__from__hash__request)
+        models           = {}
+        oldest_timestamp = None
+        newest_timestamp = None
+
+        for cache_id, entry in self.cache_entries.items():                                                          # Track models
+            model = entry.llm_request.request_data.model
+            if model in models:
+                models[model] += 1
+            else:
+                models[model] = 1
+
+            timestamp = entry.llm_response.timestamp                                                                # Track timestamps
+            if oldest_timestamp is None or timestamp < oldest_timestamp:
+                oldest_timestamp = timestamp
+            if newest_timestamp is None or timestamp > newest_timestamp:
+                newest_timestamp = timestamp
+
+        return { "total_entries" : total_entries                                       ,
+                 "models"        : models                                              ,
+                 "oldest_entry"  : str(oldest_timestamp) if oldest_timestamp else None ,
+                 "newest_entry"  : str(newest_timestamp) if newest_timestamp else None }

osbot_utils/helpers/llms/cache/LLM_Request__Cache__File_System.py

@@ -0,0 +1,237 @@
+from datetime                                                                   import datetime, UTC
+from typing                                                                     import Optional, List
+from osbot_utils.decorators.methods.cache_on_self                               import cache_on_self
+from osbot_utils.helpers.Obj_Id                                                 import Obj_Id
+from osbot_utils.helpers.Safe_Id                                                import Safe_Id
+from osbot_utils.helpers.llms.cache.LLM_Cache__Path_Generator                   import LLM_Cache__Path_Generator
+from osbot_utils.helpers.llms.cache.LLM_Request__Cache                          import LLM_Request__Cache
+from osbot_utils.helpers.llms.cache.LLM_Request__Cache__Storage                 import LLM_Request__Cache__Storage
+from osbot_utils.helpers.llms.cache.Virtual_Storage__Local__Folder              import Virtual_Storage__Local__Folder
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Cache__Index                  import Schema__LLM_Cache__Index
+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.llms.schemas.Schema__LLM_Response__Cache               import Schema__LLM_Response__Cache
+from osbot_utils.helpers.safe_str.Safe_Str__File__Path                          import Safe_Str__File__Path
+from osbot_utils.type_safe.decorators.type_safe                                 import type_safe
+
+class LLM_Request__Cache__File_System(LLM_Request__Cache):
+    virtual_storage: Virtual_Storage__Local__Folder    
+    path_generator : LLM_Cache__Path_Generator
+    shared_domains : List[Safe_Id]
+    shared_areas   : List[Safe_Id]
+    
+    @cache_on_self
+    def storage(self):
+        return LLM_Request__Cache__Storage(virtual_storage=self.virtual_storage)
+    
+    def save(self) -> bool:                                                                 # Save cache index to disk
+        self.storage().save__cache_index(cache_index=self.cache_index)
+        return True
+
+    def setup(self) -> 'LLM_Request__Cache__File_System':                                  # Load cache from disk
+        self.load_or_create()
+        return self
+
+    def get_all_cache_ids(self) -> List[Obj_Id]:                                          # Get all cache IDs from disk
+        return sorted(self.cache_index.cache_id__to__file_path.keys())
+
+    def load_cache_entry(self, cache_id: Obj_Id) -> Optional[Schema__LLM_Response__Cache]: # Load cache entry from disk
+        cache_path  = self.path_file__cache_entry(cache_id)
+        cache_entry = self.storage().load__cache_entry(cache_path)
+        if cache_entry:
+            self.cache_entries[cache_id] = cache_entry
+            return cache_entry
+        return None
+
+    def get_cache_entry(self, cache_id: Obj_Id) -> Optional[Schema__LLM_Response__Cache]:   # Get cache entry by ID (overridden)
+        if cache_id in self.cache_entries:                                                  # Check memory first
+            return self.cache_entries[cache_id]
+        return self.load_cache_entry(cache_id)                                              # Load from disk if not in memory
+
+    @type_safe
+    def delete(self, request: Schema__LLM_Request)-> bool:                                      # Delete from cache (overridden) , returns Success status
+        request_hash = self.compute_request_hash(request)
+
+        if request_hash not in self.cache_index.cache_id__from__hash__request:
+            return False
+
+        cache_id   = self.cache_index.cache_id__from__hash__request[request_hash]
+        cache_path = self.path_file__cache_entry(cache_id)
+
+        self.storage().delete__cache_entry(cache_path)                                             # Delete the file
+
+        return super().delete(request)                                                          # Remove from memory and index
+
+    def clear(self) -> bool:                                                                    # Clear all cache entries (overridden)
+        for cache_id in self.get_all_cache_ids():                                               # Delete all files
+            cache_path = self.path_file__cache_entry(cache_id)
+            self.storage().delete__cache_entry(cache_path)
+
+        self.storage().delete__cache_index()
+
+        return super().clear()                                                                  # Clear memory cache
+
+    def load_or_create(self):
+        if self.storage().exists__cache_index():                                                  # if cache file exists
+            self.cache_index = self.storage().load__cache_index()                                 # load it
+        else:
+            self.save()                                                                         # if not save the current cache_index (which should be empty)
+
+    def rebuild_cache_id_to_file_path(self) -> List[Obj_Id]:                # todo: check the performance impact of this (and if we really need this method)                                    # Get all cache IDs from disk
+        self.cache_index.cache_id__to__file_path = self.storage().reload__cache_id_to_file_path()  # assign the new cache_id__to__file_path
+        return self
+
+
+    def rebuild_index(self) -> bool:                                                            # Rebuild index from disk files
+        self.cache_index   = Schema__LLM_Cache__Index()                                         # Create new empty index
+        self.cache_entries = {}
+        self.rebuild_cache_id_to_file_path()                                                    # rebuild the cache_id_to_file_path (needed so that we can find the files from its cache_ids)
+        for cache_id in self.get_all_cache_ids():                                               # Load all cache entries
+            cache_entry = self.load_cache_entry(cache_id)
+            if cache_entry:
+                request       = cache_entry.llm_request
+                hash_request  = cache_entry.hash__request
+                if hash_request is None:                                                        # if hash_request doesn't exist     # todo: see if this a valid scenario
+                    hash_request  = self.compute_request_hash(request)                          #   recompute hash_request
+                self.cache_index.cache_id__from__hash__request[hash_request] = cache_id         # Update the index
+
+        return self.save()
+
+    # def stats(self) -> Dict:                                                               # Cache statistics (overridden)
+    #     stats = super().stats()
+    #     total_size = 0                                                                      # Add disk-specific stats
+    #
+    #     # Add index file size
+    #     index_path = self.path_file__cache_index()
+    #     if file_exists(index_path):
+    #         total_size += os.path.getsize(index_path)
+    #
+    #     # Add cache entry files size
+    #     for cache_id in self.get_all_cache_ids():
+    #         cache_path = self.path_file__cache_entry(cache_id)
+    #         if file_exists(cache_path):
+    #             total_size += os.path.getsize(cache_path)
+    #
+    #     stats["total_size_bytes"] = total_size
+    #     #stats["root_folder"     ] = self.path_folder__root_cache()
+    #     stats["cache_files"     ] = len(self.get_all_cache_ids())
+    #
+    #     return stats
+
+    # @cache_on_self
+    # def path_folder__root_cache(self):                                                     # Get root cache folder path
+    #     if folder_exists(self.root_folder):                                                # If cache_folder is a folder that exists
+    #         path_cache_folder = self.root_folder                                           #   Then use it
+    #     else:                                                                              # If not
+    #         path_cache_folder = path_combine_safe(current_temp_folder(), self.root_folder) #   Combine with temp folder
+    #         folder_create(path_cache_folder)                                               #   Make sure it exists
+    #     return path_cache_folder
+    #
+    # def path_file__cache_index(self):                                                      # Get path to cache index file
+    #     return path_combine_safe(self.path_folder__root_cache(), FILE_NAME__CACHE_INDEX)
+    #
+    def path_file__cache_entry(self, cache_id: Obj_Id) -> str:                             # Get path to cache entry file
+        file_path      = self.cache_id__to__file_path(cache_id)
+        return file_path
+    #     if file_path:
+    #         full_file_path = path_combine_safe(self.path_folder__root_cache(), file_path)
+    #         return full_file_path
+
+    @type_safe
+    def cache_id__to__file_path(self, cache_id: Obj_Id) -> str:
+        return self.cache_index.cache_id__to__file_path.get(cache_id)
+
+    @type_safe
+    def extract_domains_from_request(self, request: Schema__LLM_Request) -> List[Safe_Id]:                          # Extract organizational information from a request.
+        domains = []
+        if request and request.request_data:
+            if request.request_data.model:                                                                          # first add the model (if exists)
+                domains.append(Safe_Id(request.request_data.model))
+            if request.request_data.provider:                                                                       # then add the provider (if exists)
+                domains.append(Safe_Id(request.request_data.provider))
+            if request.request_data.platform:                                                                       # finally add the platform (if exists)
+                domains.append(Safe_Id(request.request_data.platform))
+
+        return domains
+
+    @type_safe
+    def path_for_temporal_entry(self, cache_id  : Obj_Id              ,
+                                      date_time : datetime      = None,
+                                      domains   : List[Safe_Id] = None,
+                                      areas     : List[Safe_Id] = None
+                                 ) -> Safe_Str__File__Path:                                          # Generate a time-based path for a cache entry
+        date_time = date_time or datetime.now()
+        path      = self.path_generator.from_date_time(date_time = date_time,
+                                                       domains   = domains,
+                                                       areas     = areas,
+                                                       file_id   = Safe_Id(cache_id),
+                                                       extension = "json")
+        return path
+
+    @type_safe
+    def add(self, request  : Schema__LLM_Request,
+                  response : Schema__LLM_Response,
+                  now      : datetime = None
+             ) -> Obj_Id:                                                                           # Save an LLM request/response pair using temporal organization.
+
+        cache_id        = super().add(request, response)                                            # First use standard add() to handle in-memory caching
+        cache_entry     = self.cache_entries[cache_id]                                              # get the cache entry (which will exist since it was added on super().add(request, response)  )
+        request_domains = self.extract_domains_from_request(request)                                # Extract domains and areas for organization
+        domains         = self.shared_domains + request_domains
+        areas           = self.shared_areas
+        date_time       = now or datetime.now(UTC)
+
+        file_path       = self.path_for_temporal_entry(cache_id   = cache_id ,                      # Generate file path and save
+                                                           date_time  = date_time,
+                                                           domains    = domains  ,
+                                                           areas      = areas    )
+        self.cache_index.cache_id__to__file_path[cache_id] = file_path
+
+        self.storage().save__cache_entry(file_path, cache_entry)
+
+        self.save()                                                                         # save the cache to disk
+        return cache_id
+
+    # todo: see if we need this, since we should create an MGraph with this data (also self.cache_index.cache_id__to__file_path kinda have this data)
+    # @type_safe
+    # def get_from__date_time(self,date_time: datetime,
+    #                             domains   : List[Safe_Id] = None,
+    #                             areas     : List[Safe_Id] = None) -> List[Schema__LLM_Response__Cache]:     # Get all cache entries from a specific date/time.
+    #
+    #     folder_path      = self.path_generator.from_date_time(date_time = date_time,                        # Generate the folder path pattern for the date/time
+    #                                                           domains   = domains  ,
+    #                                                           areas     = areas    )
+    #     full_folder_path = path_combine_safe(self.path_folder__root_cache(), folder_path)
+    #
+    #
+    #     if not folder_exists(full_folder_path):                                                             # Check if folder exists
+    #         return []
+    #
+    #
+    #     results = []                                                                                        # Find all cache files in this folder and subfolders
+    #     # todo: refactor using osbot_utils files methods
+    #     def collect_entries(directory):                                                                     # Function to collect entries recursively
+    #         for item in os.listdir(directory):
+    #             item_path = os.path.join(directory, item)
+    #             if os.path.isdir(item_path):
+    #                 collect_entries(item_path)
+    #             elif item.endswith('.json') and item != FILE_NAME__CACHE_INDEX:
+    #                 cache_id_str = os.path.splitext(os.path.basename(item_path))[0]
+    #                 if is_obj_id(cache_id_str):
+    #                     cache_id = Obj_Id(cache_id_str)
+    #                     cache_entry = self.get_cache_entry(cache_id)
+    #                     if cache_entry:
+    #                         results.append(cache_entry)
+    #
+    #     collect_entries(full_folder_path)
+    #     return results
+
+    # @type_safe
+    # def get_from__now(self,domains: List[Safe_Id] = None,
+    #                        areas   : List[Safe_Id] = None,
+    #                        now     : datetime      = None
+    #                   ) -> List[Schema__LLM_Response__Cache]:    # Get all cache entries from current time or specified time.
+    #     timestamp = now or datetime.now()
+    #     return self.get_from__date_time(date_time = timestamp,
+    #                                     domains   = domains  ,
+    #                                     areas     = areas    )

osbot_utils/helpers/llms/cache/LLM_Request__Cache__Storage.py

@@ -0,0 +1,85 @@
+import os
+from typing                                                                     import List, Optional
+from osbot_utils.decorators.methods.cache_on_self                               import cache_on_self
+from osbot_utils.helpers.llms.cache.Virtual_Storage__Local__Folder              import Virtual_Storage__Local__Folder
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Cache__Index                  import Schema__LLM_Cache__Index
+from osbot_utils.helpers.llms.schemas.Schema__LLM_Response__Cache               import Schema__LLM_Response__Cache
+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
+from osbot_utils.helpers.Obj_Id                                                 import Obj_Id, is_obj_id
+from osbot_utils.utils.Files                                                    import path_combine_safe, file_name_without_extension, parent_folder
+
+FILE_NAME__CACHE_INDEX            = "cache_index.json"
+
+class LLM_Request__Cache__Storage(Type_Safe):
+    virtual_storage         : Virtual_Storage__Local__Folder
+    index_file_name : str                                        = FILE_NAME__CACHE_INDEX
+
+    @type_safe
+    def delete__cache_entry(self, file_path : Safe_Str__File__Path) -> bool: # Delete cache entry from storage
+        return self.virtual_storage.file__delete(self.path_file__cache_entry(file_path))
+
+    def delete__cache_index(self):
+        index_path = self.path_file__cache_index()
+        return self.virtual_storage.file__delete(index_path)
+
+    @type_safe
+    def exists__cache_entry(self,file_path : Safe_Str__File__Path) -> bool: # Check if cache entry exists
+        return self.virtual_storage.file__exists(self.path_file__cache_entry(file_path))
+
+    def exists__cache_index(self):
+        path_cache_index = self.path_file__cache_index()
+        return self.virtual_storage.file__exists(path_cache_index)
+
+    @type_safe
+    def load__cache_entry(self, file_path : Safe_Str__File__Path) -> Optional[Schema__LLM_Response__Cache]:                 # Load cache entry from storage
+        path_entry = self.path_file__cache_entry(file_path)
+        if self.virtual_storage.file__exists(path=path_entry):
+            json_data   = self.virtual_storage.json__load(path=path_entry)
+            cache_entry = Schema__LLM_Response__Cache.from_json(json_data)
+            return cache_entry
+        return None
+
+    def load__cache_index(self) -> Optional[Schema__LLM_Cache__Index]:                                                         # Load cache index data
+        path_cache_index = self.path_file__cache_index()
+        if self.virtual_storage.file__exists(path_cache_index):
+            json_data = self.virtual_storage.json__load(path=path_cache_index)       # get the data
+            return Schema__LLM_Cache__Index.from_json(json_data)    # and load it as cache_index
+        return None
+
+    @cache_on_self
+    def path_file__cache_index(self) -> Safe_Str__File__Path:                                       # Get path to cache index file
+        path = path_combine_safe(self.virtual_storage.path_folder__root_cache(), self.index_file_name)
+        return Safe_Str__File__Path(path)
+
+    @type_safe
+    def path_file__cache_entry(self, file_path : Safe_Str__File__Path) -> Safe_Str__File__Path:     # Get full path to cache entry file
+        path = path_combine_safe(self.virtual_storage.path_folder__root_cache(), file_path)
+        return Safe_Str__File__Path(path)
+
+    def reload__cache_id_to_file_path(self) -> List[Obj_Id]:                # todo: check the performance impact of this (and if we really need this method)                                    # Get all cache IDs from disk
+        all_files_paths         = self.virtual_storage.files__all()
+        path_root               = self.virtual_storage.path_folder__root_cache()
+        cache_id__to__file_path = {}
+        for full_file_path in all_files_paths:
+            file_path = os.path.relpath(full_file_path, path_root)
+            cache_id  = file_name_without_extension(full_file_path)
+            if is_obj_id(cache_id):
+                cache_id__to__file_path[cache_id] = file_path
+        return cache_id__to__file_path
+
+    @type_safe
+    def save__cache_index(self, cache_index : Schema__LLM_Cache__Index) -> bool:                           # Save cache index data
+        json_data =  cache_index.json()
+        return self.virtual_storage.json__save(data=json_data, path=self.path_file__cache_index())
+
+    @type_safe
+    def save__cache_entry(self,file_path   : Safe_Str__File__Path,
+                               cache_entry : Schema__LLM_Response__Cache
+                          ) -> bool:                                                        # Save cache entry to storage
+        full_file_path        = Safe_Str__File__Path(path_combine_safe(self.virtual_storage.path_folder__root_cache(), file_path))
+        folder_full_file_path = parent_folder(full_file_path)
+        json_data             = cache_entry.json()
+        self.virtual_storage.folder__create(folder_full_file_path)                                               # Ensure parent folder exists
+        return self.virtual_storage.json__save(data=json_data, path=full_file_path)

osbot_utils/helpers/llms/cache/Virtual_Storage__Local__Folder.py

@@ -0,0 +1,64 @@
+from typing                                                         import List, Optional, Dict, Any
+from osbot_utils.decorators.methods.cache_on_self                   import cache_on_self
+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
+from osbot_utils.utils.Files                                        import current_temp_folder, path_combine_safe, folder_create, file_exists, folder_exists, file_delete, file_name_without_extension, parent_folder, create_folder, files_recursive
+from osbot_utils.utils.Json                                         import json_save_file, json_load_file, json_file_load
+
+FOLDER_NAME__CACHE_IN_TEMP_FOLDER = '_llm_requests_cache'
+FILE_NAME__CACHE_INDEX            = "cache_index.json"
+
+class Virtual_Storage__Local__Folder(Type_Safe):
+
+    root_folder : Safe_Str__File__Path = None                                       # Base directory for file operations
+
+    def folder__create(self, path_folder) -> None:                                  # Make sure root folder exists
+        folder_create(path_folder)
+
+    @type_safe
+    def json__load(self, path: Safe_Str__File__Path) -> Optional[Dict[str, Any]]:  # Read JSON from file
+        full_path = self.get_full_path(path)
+        if file_exists(full_path):
+            return json_load_file(path=full_path)
+        return None
+
+    @type_safe
+    def json__save(self, path: Safe_Str__File__Path,
+                         data: dict
+                    ) -> bool:                                           # Write JSON to file
+        full_path = self.get_full_path(path)
+        folder = parent_folder(full_path)
+        create_folder(folder)                                         # Ensure parent folder exists
+        return json_save_file(data, path=full_path)
+
+    @cache_on_self
+    def path_folder__root_cache(self) -> str:  # Get root cache folder path
+        if folder_exists(self.root_folder):
+            path_cache_folder = self.root_folder
+        else:
+            path_cache_folder = path_combine_safe(current_temp_folder(), self.root_folder)
+            folder_create(path_cache_folder)
+        return path_cache_folder
+
+    @type_safe
+    def get_full_path(self, path: Safe_Str__File__Path) -> Safe_Str__File__Path:    # Convert relative path to absolute
+        base_path = self.path_folder__root_cache()
+        full_path = path_combine_safe(base_path, path)
+        return Safe_Str__File__Path(full_path)
+
+    @type_safe
+    def file__delete(self, path: Safe_Str__File__Path) -> bool:        # Delete a file
+        full_path = self.get_full_path(path)
+        return file_delete(full_path)
+
+    @type_safe
+    def file__exists(self, path: Safe_Str__File__Path) -> bool:       # Check if file exists
+        full_path = self.get_full_path(path)
+        return file_exists(full_path)
+
+    @type_safe
+    def files__all(self) -> List[str]:                            # List all files recursively
+        base_path = self.path_folder__root_cache()
+        return files_recursive(base_path)
+

osbot_utils/helpers/llms/cache/Virtual_Storage__Sqlite.py

@@ -0,0 +1,72 @@
+from typing                                                         import List, Optional, Dict, Any
+from osbot_utils.decorators.methods.cache_on_self                   import cache_on_self
+from osbot_utils.helpers.safe_str.Safe_Str__File__Path              import Safe_Str__File__Path
+from osbot_utils.helpers.sqlite.domains.Sqlite__DB__Files           import Sqlite__DB__Files
+from osbot_utils.helpers.llms.cache.Virtual_Storage__Local__Folder  import Virtual_Storage__Local__Folder
+from osbot_utils.utils.Files                                        import path_combine_safe
+from osbot_utils.utils.Json                                         import json_parse, json_dumps
+
+class Virtual_Storage__Sqlite(Virtual_Storage__Local__Folder):
+    db          : Sqlite__DB__Files                                                         # SQLite database for file storage (defaults to an in memory db)
+    root_folder : Safe_Str__File__Path = Safe_Str__File__Path("llm-cache/"                )     # Prefix for all stored files
+
+    def folder__create(self, path_folder) -> None:                                          # Folders don't need to be explicitly created in SQLite storage
+        pass                                                                                # They're implicitly created when files are added with path prefixes
+
+    def json__load(self, path: Safe_Str__File__Path) -> Optional[Dict[str, Any]]:           # Load JSON data from SQLite
+        virtual_path = self.get_virtual_path(path)
+        if self.file__exists(path):
+            content = self.db.file_contents(virtual_path)
+            if content:
+                return json_parse(content)
+        return None
+
+    def json__save(self, path: Safe_Str__File__Path, data: dict) -> bool:                   # Save JSON data to SQLite
+        self.db.delete_file(path)                                                           # todo: figure out a better way to do this, since at the moment we need to delete an existing file, in order to make sure it is updated
+        virtual_path = self.get_virtual_path(path)
+        content      = json_dumps(data)
+        return self.db.add_file(virtual_path, content) is not None
+
+    def get_full_path(self, path: Safe_Str__File__Path) -> Safe_Str__File__Path:    # For SQLite, we don't need physical paths, but we maintain
+        return path                                                                 # the same interface for compatibility
+
+    def file__delete(self, path: Safe_Str__File__Path) -> bool:                     # Delete a file from SQLite
+        virtual_path = self.get_virtual_path(path)
+        return self.db.delete_file(virtual_path)
+
+    def file__exists(self, path: Safe_Str__File__Path) -> bool:                     # Check if file exists in SQLite
+        virtual_path = self.get_virtual_path(path)
+        return self.db.file_exists(virtual_path)
+
+    # todo: see if need the filter below
+    def files__all(self) -> List[str]:                                              # List all files in SQLite
+        all_files = self.db.file_names()
+        return all_files
+        #return [f for f in all_files if f.startswith(self.root_folder)]             # Filter to only include files that start with our root_prefix
+
+    def get_virtual_path(self, path: Safe_Str__File__Path) -> str:                  # Create a virtual path that incorporates the root_folder concept
+        if path.startswith(self.root_folder):
+            return path
+        return path_combine_safe(self.root_folder, path)
+
+    @cache_on_self
+    def path_folder__root_cache(self) -> str:                                       # In SQLite storage, this is a virtual concept
+        return self.root_folder                                                     # We use the root_folder as the base path for all files
+
+    def clear_all(self) -> bool:                                                    # Clear all stored files in this virtual storage
+        for file_path in self.files__all():
+            self.db.delete_file(file_path)
+        return True
+
+    def stats(self) -> Dict[str, Any]:                                              # Get storage statistics
+        total_size = 0
+        files = self.files__all()
+        for file_path in files:
+            file_info = self.db.file(file_path)
+            if file_info and 'size' in file_info:
+                total_size += file_info['size']
+
+        return { "storage_type"    : "sqlite"       ,
+                 "db_path"         : self.db.db_path,
+                 "file_count"      : len(files)     ,
+                 "total_size_bytes": total_size     }

osbot_utils/helpers/llms/platforms/open_ai/API__LLM__Open_AI.py

@@ -0,0 +1,55 @@
+from typing                             import Dict, Any
+from urllib.error                       import HTTPError
+from osbot_utils.type_safe.Type_Safe    import Type_Safe
+from osbot_utils.utils.Env              import get_env
+from osbot_utils.utils.Http             import POST_json
+from osbot_utils.utils.Json             import json_parse, str_to_json
+
+DEFAULT__LLM__SELECTED_PLATFORM = "OpenAI (Paid)"
+DEFAULT__LLM__SELECTED_PROVIDER = "OpenAI"
+DEFAULT__LLM__SELECTED_MODEL    = "gpt-4o"
+
+ENV_NAME_OPEN_AI__API_KEY = "OPEN_AI__API_KEY"
+
+class API__LLM__Open_AI(Type_Safe):
+    api_url     : str = "https://api.openai.com/v1/chat/completions"
+    api_key_name: str = ENV_NAME_OPEN_AI__API_KEY
+
+    def execute(self, llm_payload : Dict[str, Any]):
+        url = self.api_url
+
+        headers = { "Authorization": f"Bearer {self.api_key()}",
+                    "Content-Type" : "application/json"       ,
+                    'User-Agent'   : "myfeeds.ai"             }
+        try:
+            response = POST_json(url, headers=headers, data=llm_payload)
+            return response
+        except HTTPError as error:
+
+            error_message = str_to_json(error.file.read().decode('utf-8'))
+            raise ValueError(error_message)
+
+
+    # todo: refactor this into a separate class with better error detection and context specific methods
+    def get_json(self, llm_response):
+        choices  = llm_response.get('choices')
+        if len(choices) == 1:
+            message = choices[0].get('message')
+            if 'function_call' in message:
+                arguments = message.get('function_call').get('arguments')
+            else:
+                arguments = message.get('tool_calls')[0].get('function').get('arguments')
+        else:
+            return choices
+        return json_parse(arguments)
+
+    def api_key(self):
+        api_key = get_env(self.api_key_name)
+        if not api_key:
+            raise ValueError("{self.api_key_name} key not set")
+        return api_key
+
+
+    def get_json__entities(self, llm_response):
+        function_arguments = self.get_json(llm_response)
+        return function_arguments.get('entities')

osbot_utils/helpers/llms/schemas/Schema__LLM_Cache__Index.py

@@ -0,0 +1,9 @@
+from typing                                             import Dict
+from osbot_utils.helpers.Obj_Id                         import Obj_Id
+from osbot_utils.helpers.safe_str.Safe_Str__File__Path  import Safe_Str__File__Path
+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_Cache__Index(Type_Safe):
+    cache_id__from__hash__request : Dict[Safe_Str__Hash, Obj_Id]                     # map hash of the full request to a Schema__LLM_Response__Cache to the cache_id
+    cache_id__to__file_path       : Dict[Obj_Id        , Safe_Str__File__Path]       # map the cache_id to the file that holds the data

osbot_utils/helpers/llms/schemas/Schema__LLM_Request.py

@@ -0,0 +1,7 @@
+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
+
+
+class Schema__LLM_Request(Type_Safe):
+    #request_id   : Obj_Id                      # can't put this id here or we won't be able to cache this data
+    request_data : Schema__LLM_Request__Data