cached-openai 0.0.1__py3-none-any.whl

cached_openai/__init__.py

@@ -0,0 +1,10 @@
+# Make the main entrypoints into the package available at the top level of the package
+from .main import OpenAI, AsyncOpenAI, DEV_MODE
+
+# Make the materialization functions available at the top level of the package, if
+# we're in dev mode
+if DEV_MODE:
+    from .main import materialize
+
+# Remove DEV_MODE from the namespace
+del DEV_MODE

cached_openai/cached_client.py

@@ -0,0 +1,431 @@
+import openai
+import hashlib
+import json
+import os
+import base64
+import pathlib
+import time
+import asyncio
+import pickle
+import copy
+import requests
+import io
+import struct
+import inspect
+
+# There are some keywords that - when provided to an OpenAI function - do not change
+# the result; we should ignore these completely when caching results
+IRRELEVANT_KWARGS     = ['timeout']
+
+class CachedClient():
+    '''
+    This CachedClient object replicates the openai.OpenAI client object, but allows the loading
+    and saving of results to or from cache every time a request is made.
+
+    It can be created in two circumstances:
+      - When it is created by the user, it will be created with stem = []
+      - When the user accesses a method of this class, a new class is recursively created with
+        the stem extended by the attribute accessed. For example, if the user calls
+            client.chat.completion.create
+        the last CachedClient instance will have stem = ['chat', 'completion', 'create']. This
+        final instance can then be called, which will called the corresponding function in the
+        original OpenAI library
+    '''
+
+    def __init__(self,
+                 api_key             : str | None     ,
+                 cache               : dict           ,
+                 verbose             : bool           ,
+                 dev_mode            : bool           ,
+                 is_async            : bool           ,
+                 delay_responses     : bool           ,
+                 temp_cache_file     : str            , 
+                 used_keys_file      : str            ,
+                 stem                : list[str] = [] ,
+                 last_entry_returned : dict      = {}  ):
+        
+        # Store variables
+        self._api_key         = api_key
+        self._cache           = cache
+        self._verbose         = verbose
+        self._dev_mode        = dev_mode
+        self._is_async        = is_async
+        self._delay_responses = delay_responses
+        self._temp_cache_file = temp_cache_file
+        self._used_keys_file  = used_keys_file
+        self._stem            = stem
+
+        # If we were not given an API key, check whether one is available in an openai_key.txt file
+        if self._api_key is None:
+            try:
+                with open('openai_key.txt', 'r') as f:
+                    self._api_key = f.read().strip()
+                
+                if verbose:
+                    print('Read API key from openai_key.txt')
+            except:
+                pass
+            
+        # In some cases, we have multiple results for a single set of keys; this is so that
+        # we can simulate the "real" OpenAI API that would return different results every time
+        # it is run. Initialize a dictionary to store how many responses we've returned for a
+        # given key, so that we know the next one we should return next time it is called
+        self._last_entry_returned = last_entry_returned
+        
+    def __getattr__(self, name : str):
+        '''
+        This function is called whenever an instance of this class is accessed with a .;
+        for example, client.chat.
+
+        When this happens, we add the attribute being accessed to self._stem, and return
+        a new CachedClient instance with that new stem.
+        '''
+
+        return CachedClient(api_key             = self._api_key,
+                            cache               = self._cache,
+                            verbose             = self._verbose,
+                            dev_mode            = self._dev_mode,
+                            is_async            = self._is_async,
+                            delay_responses     = self._delay_responses,
+                            temp_cache_file     = self._temp_cache_file,
+                            used_keys_file      = self._used_keys_file,
+                            stem                = self._stem + [name],
+                            last_entry_returned = self._last_entry_returned    )
+
+    def get_cache_key(self, kwargs, hash_key : bool, strip_seed : bool = False):
+        '''
+        This function returns the cache key for the fuction described in self._stem called with
+        parameters kwargs. If hash_key is True, the JSon key will be hashed, otherwise it will
+        be returned raw
+        
+        The following modifications are made:
+          - If strip_seed is True, the seed parameter is removed from the kwargs
+          - Any of the arguments in IRRELEVANT_KWARGS are in kwargs, they are removed
+          - If 'with_raw_response' is in the stem, it is stripped from it; when this is is included
+            in an OpenAI API call, it is because the developer wants to get the raw response, which
+            includes the number of token's left in the user's quota. It makes no sense to store this
+            in the cache as it will be different every time
+        '''
+
+        if strip_seed:
+            kwargs = {k:v for k,v in kwargs.items() if k != 'seed'}
+        
+        this_stem = self._stem
+        this_stem = [i for i in this_stem if i != 'with_raw_response']
+
+        # Remove any irrelevant kwargs
+        kwargs = {k:v for k,v in kwargs.items() if k not in IRRELEVANT_KWARGS}
+
+        key = json.dumps({'stem':this_stem, 'kwargs':kwargs}, sort_keys=True)
+        if hash_key:
+            return hashlib.md5(key.encode('utf-8')).hexdigest()
+        else:
+            return key
+
+    def read_from_cache(self, kwargs):
+        '''
+        This function will attempt to read the cached result for the function described in self._stem
+        called with parameters kwargs.
+
+        It will return a dictionary with two entries:
+          - out : the entry in question
+          - run_time : the time the function took to run when it was initially added to the cache
+        If the entry is not found int he cache, None is returned
+        '''
+
+        # Remove any irrelevant kwargs
+        kwargs = {k:v for k,v in kwargs.items() if k not in IRRELEVANT_KWARGS}
+
+        # Try and the find the value in the cache; first, look for the raw JSon, and if it's not found
+        # look for the hashed key. Do NOT strip the seed - if the user intentionally added a seed argument,
+        # we want THAT entry specifically
+        key = self.get_cache_key(kwargs, hash_key = False)
+        if key not in self._cache:
+            key = self.get_cache_key(kwargs, hash_key = True)
+        
+        # Check whether we have a result
+        if key in self._cache:
+            print('Found a saved result in the cache')
+            
+            # Retrieve the entry from the cache
+            cache_entry = self._cache[key]
+
+            # Check whether this cache_entry is of one of two specific types:
+            #   - A pointer (a dictionary with a single entry with the key 'TARGET'), pointing to
+            #     another entry in the cache. If we have such an entry, we need to follow it
+            #   - A list, in which case there are many possible results for this key, and we need
+            #     to return the next one
+
+            while (type(cache_entry) == list) or ('TARGET' in cache_entry):
+                if type(cache_entry) == list:
+                    # Find the next entry to retrieve from the list, wrapping back to the front of
+                    # the list if we reach the end
+                    self._last_entry_returned[key] = (self._last_entry_returned.get(key, -1) + 1) % len(cache_entry)
+                    cache_entry = cache_entry[self._last_entry_returned[key]]
+                elif 'TARGET' in cache_entry:
+                    # Log the fact we used this key, and then follow the pointer
+                    if self._dev_mode:
+                        with open(self._used_keys_file, 'a') as f : f.write(key + '\n')
+                    
+                    key = cache_entry['TARGET']
+                    cache_entry = self._cache[key]
+            
+            # Record the fact we've used the key
+            if self._dev_mode:
+                with open(self._used_keys_file, 'a') as f: f.write(key + '\n')
+            
+            # Retrieve the output that was saved from OpenAI
+            out = cache_entry['out']
+
+            # If the cache_entry contains a 'saved_images' entry, handle the images returned by the
+            # API
+            if 'saved_images' in cache_entry:
+                # Make sure we don't mutate the original object in the cache
+                out = copy.deepcopy(out)
+
+                # Get the saved images that were downloaded the cache
+                saved_images = cache_entry['saved_images']
+
+                # out.data is the entry in the OpenAI object that contains the image URLs. saved_images
+                # contains the actual image data. We want to save those images as a file, and replace
+                # the URL in out.data with the URL of the new file
+                for im, saved_im in zip(out.data, saved_images):
+                    if saved_im is not None:
+                        # Create a file name for this image based on the hash of the URL
+                        file_name = hashlib.md5((key + im.url).encode('utf-8')).hexdigest() + '.png'
+
+                        # Check whether the images folder exists; if not, create it
+                        if not os.path.exists('images'):
+                            os.mkdir('images')
+
+                        # Save the image there
+                        with open(f'images/{file_name}', 'wb') as f:
+                            f.write(saved_im)
+
+                        # Alter the URL in the output object
+                        im.url = pathlib.Path(f'images/{file_name}').resolve().as_uri()
+
+            # If the cache_entry contains an 'audio_file' entry, deal with the audio file
+            if 'audio_file' in cache_entry:
+                # Create a class that will allow us to use a iter_bytes method and a stream_to_file
+                # method
+                class Stream:
+                    def __init__(self, bytes):
+                        self.byte_stream = io.ByteIO(bytes)
+                    
+                    def iter_bytes(self):
+                        while True:
+                            chunk = self.byte_stream(1024)
+                            if not chunk:
+                                break
+                            yield chunk
+                    
+                    def stream_to_file(self, file_name):
+                        with open(file_name, 'wb') as f:
+                            f.write(self.byte_stream.getvalue())
+
+
+                if cache_entry['audio_file'][0] == 'old':
+                    return {'out'      : Stream(cache_entry['audio_file'][1]),
+                            'run_time' : cache_entry['run_time']               }
+                
+                elif cache_entry['audio_file'][0] == 'new':
+                    # Create a class that we can use as a context manager to return the Stream
+                    # object
+                    class AudioFile:
+                        def __enter__(self):
+                            return Stream(cache_entry['audio_file'][1])
+                            
+                        def __exit__(self, exc_type, exc_value, traceback):
+                            pass
+
+                        def __call__(self):
+                            return self
+                    
+                    return {'out'      : AudioFile(),
+                            'run_time' : cache_entry['run_time']}
+
+            # If we reached this point, we don't have an audio file - return
+            return {'out'      : out,
+                    'run_time' : cache_entry['run_time']}
+        else:
+            if self._verbose:
+                print('No saved result found')
+
+            return None
+
+    def modify_cache(self, key, value):
+        '''
+        This function writes a specific key and value to the cache and the temporary cache
+        file, and records the fact the key has been used
+        '''
+
+        # Record in the cache
+        self._cache[key] = value
+        
+        # Save the value to the temporary cache file 
+        with open(self._temp_cache_file, 'ab') as f:
+            # Get the entry
+            entry = pickle.dumps([key, value])
+
+            # Write its length to the file
+            f.write(struct.pack('I', len(entry)))
+
+            # Then, write the entry
+            f.write(entry)
+
+        # Record the fact the key has been used
+        with open(self._used_keys_file, 'a') as f:
+            f.write(key + '\n')
+
+    def write_to_cache(self, kwargs, out, run_time):
+        '''
+        If we are in dev mode, this function will write the result of the function
+        described in self._stem called with parameters kwargs to the cache.
+
+        It also adds the result ot the temporary cache file
+        '''
+
+        if self._dev_mode:
+            if self._verbose:
+                print('Saving result to the cache')
+
+            # If we asked for the raw response from the OpenAI API, get the parsed response - we
+            # do NOT want to save the raw response to the cache, because it contains things like
+            # the number of tokens remaining, which won't be relevant/valid when the value is
+            # pulled from the ache
+            if 'with_raw_response' in self._stem:
+                out = out.parse()
+            
+            # Prepare the output object
+            out_obj = {'out':out, 'time_saved':time.time(), 'run_time':run_time}
+
+            # Check whether this is a request throught the image API - if so, we need to check
+            # whether URLs were returned; if they were, we should save them
+            if 'images' in self._stem:
+                saved_images = []
+                for im in out.data:
+                    if im.url:
+                        saved_images.append(requests.get(im.url).content)
+                    else:
+                        saved_images.append(None)
+                out_obj['saved_images'] = saved_images
+
+            # Check whether this is a request throught he audio API - if so, we need to download
+            # the resulting file, and save it. Unfortunately, there are two ways this API might
+            # be called - the legacy way (client.audio.speech.create) and the new way (client.
+            # audio.speech.with_streaming_response.create). They each require different ways to
+            # download the file
+            if type(out) == openai._legacy_response.HttpxBinaryResponseContent:
+                # The user used the legacy format; get the file in base64 format
+                audio_data = io.BytesIO()
+                for chunk in out.iter_bytes():
+                    audio_data.write(chunk)
+                audio_data.seek(0)
+                audio_data = audio_data.read()
+                audio_data = base64.b64encode(audio_data).decode('utf-8')
+
+                out_obj['audio_file'] = ('old', audio_data)
+            
+            if type(out) == openai._response.ResponseContextManager:
+                # The user used the new format; get the file in base64 format
+                audio_data = io.BytesIO()
+                with out as _out:
+                    for chunk in _out.iter_bytes():
+                        audio_data.write(chunk)
+                audio_data.seek(0)
+                audio_data = audio_data.read()
+                audio_data = base64.b64encode(audio_data).decode('utf-8')
+
+                out_obj['audio_file'] = ('new', audio_data)
+
+            # First, save the entry as provided
+            seeded_key = self.get_cache_key(kwargs, hash_key=False)
+
+            if 'seed' in kwargs:
+                # If this call includes a seed, we just want to overwrite whatever already exists in
+                # the cache at that position
+                self.modify_cache(seeded_key, [out_obj])
+
+                # Now, strip the seed, and look at the corresponding entry - if a pointer to this
+                # seeded entry doesn't yet exist there, add it
+                stripped_key = self.get_cache_key(kwargs, strip_seed=True, hash_key=False)
+
+                current_pointers = [i['TARGET'] for i in self._cache.get(stripped_key, []) if 'TARGET' in i]
+
+                if seeded_key not in current_pointers:
+                    self.modify_cache(stripped_key, self._cache.get(stripped_key, []) + [{'TARGET':seeded_key}])
+            else:
+                # This isn't a seeded request. If we already have an entry there, append this request
+                # to the list
+                self.modify_cache(seeded_key, self._cache.get(seeded_key, []) + [out_obj])
+                
+    def __call__(self, **kwargs):
+        '''
+        This function is called whenever an OpenAI function is called
+        '''
+
+        # Try and read the value from the cache
+        out = self.read_from_cache(kwargs)
+
+        if out is not None:
+            # We were able to pull a value from the cache; return either the value, or an async
+            # funcion that returns it. Pause if needed.
+
+            if self._is_async:
+                async def async_func():
+                    if self._delay_responses:
+                        await asyncio.sleep(out['run_time'])
+                    return out['out']
+                return async_func()
+            
+            else:
+                if self._delay_responses:
+                    time.sleep(out['run_time'])
+                return out['out']
+        
+        # If we reached this point, we need to query OpenAI. Make sure we have an OpenAI key
+        if self._api_key is None:
+            raise ValueError('Your request is not available in the cache, and you did not provide '
+                             "an OpenAI API key, so I can't query OpenAI for you.")
+        
+        # Create a "real" openai.OpenAI client object (sync or async as needed)
+        if self._is_async:
+            rel_func = openai.AsyncOpenAI(api_key=self._api_key)
+        else:
+            rel_func = openai.OpenAI(api_key=self._api_key)
+
+        # Go down the stem tree to find the relevant function
+        for attr in self._stem:
+            rel_func = getattr(rel_func, attr)
+
+        # If the function was called with a seed but the OpenAI function does not accept one,
+        # strip it before calling
+        kwargs_copy = {i:j for i, j in kwargs.items()}
+        if 'seed' not in inspect.signature(rel_func).parameters:
+            if 'seed' in kwargs_copy:
+                if self._verbose:
+                    print('Detected a seed parameter in an OpenAPI call that does not accept a seed. '
+                          "I'll strip the parameter from the call before sending it to OpenAI, but "
+                          "save it in the cached response. See the user manual (section 'repeated "
+                          "requests') for details" )
+                kwargs_copy = {i:j for i, j in kwargs.items() if i != 'seed'}
+            
+
+        # Call it, write the result to the cache, and return either the value or the co-routine
+        # if we are in async mode
+        if self._is_async:
+            async def async_func():
+                start_time = time.time()
+                out = await rel_func(**kwargs_copy)
+                self.write_to_cache(kwargs, out, time.time() - start_time)
+                return out
+            
+            return async_func()
+        
+        else:
+            start_time = time.time()
+            out = rel_func(**kwargs_copy)
+            self.write_to_cache(kwargs, out, time.time() - start_time)
+
+            return out

cached_openai/main.py

@@ -0,0 +1,150 @@
+# File utilities
+import os
+from . import utils
+from . import cached_client
+from . import materialize_utils
+import datetime
+
+######################
+#  Define constants  #
+######################
+
+# Specify the name of the permanent cache file. We will first look for this file
+# in the working directory; if it exists there, we load it from there. If it
+# doesn't, we look for it in the package directory
+CACHE_FILE_NAME       = 'openai.cache'
+
+# Determine whether we want to print debugging information as we run the package;
+# this is required if the 'CACHED_OPENAI_VERBOSE' variable is set in the
+# environment
+VERBOSE               = 'CACHED_OPENAI_VERBOSE' in os.environ
+
+# In dev mode, all calls to the open AI API will be cached in the temporary cache
+# file, and every time a request is made (either new or cached), we will track
+# the fact the request has been made in a used keys file. The latter allows a
+# "cleaning operation" that only keeps data for requests that have been made
+# since this file was created.
+#
+# Dev mode is turned on if the 'CACHED_OPENAI_DEV_MODE' variable is set in the
+# environment
+DEV_MODE              = 'CACHED_OPENAI_DEV_MODE' in os.environ
+if VERBOSE:
+    print(f'DEV_MODE is set to {DEV_MODE}')
+
+# The name of the temporary cache and used keys files which will be written to in
+# dev mode. These will be in the code's working directory
+TEMP_CACHE_FILE_NAME  = 'openai_cache_temp.bin' 
+USED_KEYS_FILE        = 'openai_cache_used.txt'
+
+# When we recover values form the cache, we can either return the values instantly
+# or delay for as long as it took to originally get a response from the OpenAI
+# API. By default, no pausing will happen, unless a 'CACHED_OPENAI_DELAY_RESPONSES'
+# variable is set in the environment 
+DELAY_RESPONSES_NEW   = 'CACHED_OPENAI_DELAY_RESPONSES' in os.environ
+if VERBOSE:
+    print(f'DELAY_RESPONSES is set to {DELAY_RESPONSES_NEW}')
+
+###########
+#  Setup  #
+###########
+
+# Load the cache
+delay_responses, cache = utils.get_cache(CACHE_FILE_NAME, TEMP_CACHE_FILE_NAME, DEV_MODE, DELAY_RESPONSES_NEW, VERBOSE)
+
+#################################################
+#  Create the main entrypoints for the package  #
+#################################################
+
+def OpenAI(api_key : str | None = None):
+    return cached_client.CachedClient(                  api_key                   ,
+                                      cache           = cache                     ,
+                                      verbose         = VERBOSE                   ,
+                                      dev_mode        = DEV_MODE                  ,
+                                      is_async        = False                     ,
+                                      delay_responses = delay_responses           ,
+                                      temp_cache_file = TEMP_CACHE_FILE_NAME      ,
+                                      used_keys_file  = USED_KEYS_FILE              )
+
+def AsyncOpenAI(api_key : str | None = None):
+    return cached_client.CachedClient(                 api_key                    ,
+                                      cache           = cache                     ,
+                                      verbose         = VERBOSE                   ,
+                                      dev_mode        = DEV_MODE                  ,
+                                      is_async        = True                      ,
+                                      delay_responses = delay_responses           ,
+                                      temp_cache_file = TEMP_CACHE_FILE_NAME      ,
+                                      used_keys_file  = USED_KEYS_FILE              )
+
+##########################################
+#  Create the materialization functions  #
+##########################################
+
+def materialize(self_contained : bool,
+                compress       : bool,
+                hash_keys      : bool,
+                used_keys_only : bool):
+    '''
+    This function materilizes the cache and prepares it for distribution. It accepts
+    the following options
+      - self_contained : if True, the function will create a file called
+        cached_openai_{date}.py in the current working directory which will contain
+        the materialized cache. This file will be a self-contained .py file containing
+        a serialized verison of the cache. Just import that package, and you're good
+        to go with the full cache.
+
+        If False, the function will create a file called named openai_{date}.cache
+        containing the cache only. The file can be distributed in three ways
+          - Rename it to openai.cache, and ask your target audience to place the file
+            in their working directory. They can then install cached_openai through
+            pypi, and when they load the package, it will find the file in the working
+            directory and load it
+          - Upload it to some URL. Then, get your audience to install cached_openai
+            from pypi. When they load the package, it will prompt them for the URL,
+            from which the file will autoomatically be downloaded
+          - Fork cached_openai, rename the file to openai.cache, and include it in
+            the src directory of the package. Publish it. When your target audience
+            downloads the package, the cache will be read from this file.
+
+      - compress: True if the cache should be compressed before saving or false
+        otherwise. Note that this means the package will take longer to run every time
+        it is loaded 
+      
+      - hash_keys : whether keys should be hashed; if True, the dictionary keys will be hashed
+        and the pickle file will be smaller. On the other hand, the cache will then become
+        *final* - it will be impossible to add to it. If you choose to go the hashed direction,
+        it is recommended you first save the cache without hashing the keys so that you can
+        later add to it if you like
+
+      - used_keys_only : if True, the cache will only contain the keys that have been
+        created or access since the last time the openai_cache_used.txt file was created.
+
+        This is useful if you fill the cache with a whole bunch of data while you test
+        your code, and then want to create a "clean" version to distribute. Just delete the
+        openai_cache_used.txt file, run you clean code, and then run this with used_keys_only
+        = True.
+    '''
+
+    current_date = datetime.datetime.now().strftime('%Y-%m-%d')
+
+    if used_keys_only:
+        with open(USED_KEYS_FILE, 'r') as f:
+            used_keys = f.read().split('\n')
+    else:
+        used_keys = None
+
+    if self_contained:
+        materialize_utils.create_self_contained(cache           = cache,
+                                                delay_responses = delay_responses,
+                                                compress        = compress,
+                                                hash_keys       = hash_keys,
+                                                file_name       = f'cached_openai_{current_date}.py',
+                                                used_keys       = used_keys)
+    else:
+        materialize_utils.materialize_cache(cache           = cache,
+                                            delay_responses = delay_responses,
+                                            compress        = compress,
+                                            hash_keys       = hash_keys,
+                                            file_name       = CACHE_FILE_NAME.split('.')[0]
+                                                                    + f'_{current_date}.'
+                                                                        + CACHE_FILE_NAME.split('.')[-1],
+                                            used_keys       = used_keys)

cached_openai/materialize_utils.py

@@ -0,0 +1,118 @@
+################################
+#   Materialization utilities  #
+################################
+
+import gzip
+import pickle
+import base64
+import hashlib
+import importlib
+
+# This file contains utilities to materialize the cache into a form that
+# can be distributed
+
+def materialize_cache(cache           : dict,
+                      delay_responses : bool,
+                      compress        : bool,
+                      hash_keys       : bool,
+                      file_name       : str | None,
+                      used_keys       : list | None = None) -> str | None:
+    '''
+    This function materializes the cache into a pickle file for distribution. It accepts
+    the following arguments:
+      - cache : the cache to be saved
+      - compress : whether the cache should be compressed
+      - hash_keys : whether keys should be hashed; if yes, the dictionary keys will be hashed
+                    and the pickle file will be smaller. On the other hand, the cache will then
+                    become *final* - it will be impossible to add to it. If you choose to go
+                    the hashed direction, it is recommended you first save the cache without
+                    hashing the keys so that you can later add to it if you like
+      - file_name : the file name to be used. If no filename is provided, a base64 encoded
+                    string is returned
+      - used_keys : a list of keys that should be included in the cache; any keys are that are
+                    not included in this list are discarded
+    '''
+
+    # If we want used keys only, filter down the cache
+    if used_keys:
+        cache = {i:j for i, j in cache.items() if i in used_keys}
+
+    # If we want to hash the keys, go ahead and do it
+    if hash_keys:
+        cache = {hashlib.md5(i.encode('utf-8')).hexdigest():j
+                                        for i, j in cache.items()}
+        
+        # Make all pointers point to hashed values
+        for key, vals in cache.items():
+            for val in vals:
+                if 'TARGET' in val:
+                    val['TARGET'] = hashlib.md5(val['TARGET'].encode('utf-8')).hexdigest()
+
+    # Pickle the dictionary
+    pickled_data = pickle.dumps((delay_responses, cache))
+
+    # Compress it if needed
+    if compress:
+        pickled_data = gzip.compress(pickled_data)
+    
+    # If the filename is provided, save it there; otherwise, return a b64 encoded
+    # string
+    if file_name:
+        with open(file_name, 'wb') as f:
+            f.write(pickled_data)
+    
+    else:
+        return base64.b64encode(pickled_data).decode('utf-8')
+    
+def create_self_contained(cache           : dict,
+                          delay_responses : bool,
+                          compress        : bool,
+                          hash_keys       : bool,
+                          file_name       : str | None,
+                          used_keys       : list | None = None) -> str | None:
+    '''
+    Returns a self-contained .py file that includes the cache inside of it.
+
+    See _materialized_cache for an explanation of the arguments
+    '''
+
+    # Create a placeholder for the output code
+    out_code = []
+
+    # Get the cache as a base 64 encoded string; do not include the file name to
+    # ensure nothing is saved
+    b64_cache = materialize_cache(cache, delay_responses, compress, hash_keys, None, used_keys)
+
+    # Ensure only the OpenAI and AsyncOpenAI functions are exposed
+    out_code.append("__all__ = ['OpenAI', 'AsyncOpenAI']")
+
+    # Add the cache and the code to decompress it to the self-contained file
+    out_code.append('import base64')
+    out_code.append('import pickle')
+    out_code.append(f'cache = base64.b64decode("{b64_cache}")')
+
+    if compress:
+        out_code.append('import gzip')
+        out_code.append('cache = gzip.decompress(cache)')
+        
+    out_code.append('DELAY_RESPONSES, cache = pickle.loads(cache)')
+
+    # Load the cached_client.py file
+    with open(importlib.resources.files(__package__).joinpath('cached_client.py'), 'r') as f:
+        out_code.extend(f.read().split('\n'))
+    
+    # Create the main entrypoints
+    entrypoint_args = ( '                  api_key          ,'
+                        'cache           = cache            ,'
+                        'verbose         = False            ,'
+                        'dev_mode        = False            ,'
+                        'delay_responses = DELAY_RESPONSES  ,'
+                        'temp_cache_file = None             ,'
+                        'used_keys_file  = None             ')
+    
+    out_code.append(f'def OpenAI     (api_key : str | None = None) : return CachedClient({entrypoint_args}, is_async = False)')
+    out_code.append(f'def AsyncOpenAI(api_key : str | None = None) : return CachedClient({entrypoint_args}, is_async = True)' )
+
+    # Save the result
+    with open(file_name, 'w') as f:
+        f.write('\n'.join(out_code))

cached_openai/utils.py

@@ -0,0 +1,194 @@
+import requests
+import gzip
+import tqdm
+import os
+import importlib.resources
+import pickle
+import struct
+
+def download_cache(cache_url : str, target_file : str) -> None:
+    '''
+    This function takes the URL of a cache file, downloads it (with a progress bar) and saves
+    it to the target_file. If the URL extension ends with .gz, the file is unzipped as it
+    downloads
+    '''
+
+    # If the URL is incomplete, prepend https://
+    if not (cache_url.startswith('http://') or cache_url.startswith('https://')):
+        cache_url = 'https://' + cache_url
+
+    # Check whether the file is a .gz file
+    is_gz = cache_url.endswith('.gz')
+
+    # Start the request
+    with requests.get(cache_url, stream=True) as response:
+        # Raise an error if the request was unsuccessful
+        response.raise_for_status()
+
+        # Get the total size and prepare the progress bar
+        total_size = int(response.headers.get('content-length', 0))
+        progress_bar = tqdm.tqdm(total=total_size, unit='B', unit_scale=True, desc='Downloading cache file')
+
+        if is_gz:
+            # Monkey patch the read method
+            original_read = response.raw.read
+            def new_read(chunk_size=-1):
+                data = original_read(chunk_size)
+                if data:
+                    progress_bar.update(len(data))
+                return data
+            response.raw.read = new_read
+
+            with gzip.GzipFile(fileobj=response.raw, mode='rb') as gz_in, open(target_file, 'wb') as f:
+                while True:
+                    data = gz_in.read(8192)
+                    if not data:
+                        break
+                    f.write(data)
+
+        else:
+            with open(target_file, 'wb') as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        f.write(chunk)
+                        progress_bar.update(len(chunk))
+        
+        progress_bar.close()
+
+def load_cache_file(cache_file : bytes) -> dict:
+    '''
+    This function accept a bytes string containing a pickled object; if first checks
+    whether it can be loaded uncompressed, and if not, it tries to load it as a
+    compressed file
+    
+    It returns the object from the pickle
+    '''
+
+    try:
+        return pickle.loads(cache_file)
+    except:
+        try:
+            return pickle.loads(gzip.decompress(cache_file))
+        except:
+            raise ValueError('Invalid cache file provided')
+
+def get_cache(cache_file_name      : str          ,
+              temp_cache_file_name : str          ,
+              dev_mode             : bool         ,
+              delay_responses_new  : bool         ,
+              verbose              : bool = False  ) -> tuple[bool, dict]:
+    '''
+    This function attempts to load the cache from disk, in the following order of priority
+      - First, we look in the working directory
+      - Then, we look in the directory containing the package
+      - Finally, two options
+          * If we are in dev mode, we create a blank cache
+          * Otherwise, we prompt the user for a URL to download the cache therefrom 
+            (compressed or not). It saves it in the working directory with the name
+            cache_file_name
+    
+    If we are in dev_mode, additionally carry out the following tasks
+      - Try and load the temporary cache file, if it exists, and update the main cache
+        with it
+      - If the delay_responses parameter has changed (i.e., if delay_responses in the cache
+        file is not equal to delay_responses_new), it is overwritten in the cache file
+    
+    It returns a tuple with two entries
+      - The value of delay_responses to use
+      - The cache
+    '''
+
+    # Load the existing cache
+    # -----------------------
+
+    # Get the location of the package in case we need it later
+    package_location = importlib.resources.files(__package__)
+
+    # Determine the location of the cache file
+    if os.path.exists(cache_file_name):
+        # First, look in the working directory
+        cache_loc = cache_file_name
+        
+        if verbose:
+            print('Cache file found in the working directory.')
+
+    elif os.path.exists(package_location.joinpath(cache_file_name)):
+        # If there is no cache file in the working directory, look in the package
+        # directory
+        cache_loc = package_location.joinpath(CACHE_FILE_NAME)
+        
+        if verbose:
+            print('Cache file found in the package directory.')
+
+    else:
+        # If we have neither and we are in dev mode, start with an empty cache; if not
+        # ask the user whether they want to download a cache file, and download it to the
+        # working directory
+        if dev_mode:
+            print('No cache file was found; starting with an empty cache. It will be saved in '
+                    f'your working directory, with the name {cache_file_name}.')
+            cache_loc = cache_file_name
+            pickle.dump((delay_responses_new, {}), open(cache_loc, 'wb'))
+
+        else:
+            cache_url = input('No cache file found; please enter a URL to download a cache file from\n')
+
+            try:
+                download_cache(cache_url, cache_file_name)
+                cache_loc = cache_file_name
+                
+                print('Cache file downloaded successfully.')
+            except:
+                print('Failed to download cache file')
+                raise
+    
+    # Finally, read the cache file
+    with open(cache_loc, 'rb') as f : data = f.read()
+    delay_responses, cache = load_cache_file(data)
+    
+    # Update with the temporary cache file, or the new delay_responses value
+    # ----------------------------------------------------------------------
+
+    # If we are in dev mode, load any temporary cache file, and update the cache with it; then,
+    # re-save the updated cache
+    if dev_mode:
+        if os.path.exists(temp_cache_file_name):
+            if verbose:
+                print('Temporary cache file found; using it to update the cache.')
+            
+            # Load the temporary cache file
+            with open(temp_cache_file_name, 'rb') as f:
+                while True:
+                    # Read the length of the next entry; break if we're reached the end of
+                    # the file
+                    length_data = f.read(4)
+                    if not length_data:
+                        break
+                    length = struct.unpack('I', length_data)[0]
+
+                    key, value = pickle.loads(f.read(length))
+
+                    cache[key] = value
+
+            # Re-save the cache (note that in dev mode, we always save it uncompressed)
+            # Use the new delay_responses value
+            pickle.dump((delay_responses_new, cache), open(cache_loc, 'wb'))
+
+            # Delete the temporary cache file
+            os.remove(temp_cache_file_name)
+
+            if verbose:
+                print('Cache updated and re-saved. Temporary cache file deleted')
+
+        elif delay_responses_new != delay_responses:
+            pickle.dump((delay_responses_new, cache), open(cache_loc, 'wb'))
+
+            if verbose:
+                print('delay_responses value was changed - cache re-saved')
+
+        # Set the value of delay_responses to the new value
+        delay_responses = delay_responses_new
+
+    # Return
+    # ------
+    return delay_responses, cache

cached_openai-0.0.1.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: cached_openai
+Version: 0.0.1
+Summary: A version of the OpenAI package that allows the caching of responses
+Project-URL: Homepage, https://github.com/danguetta/cached_openai
+Project-URL: Issues, https://github.com/danguetta/cached_openai/issues
+Author-email: Daniel Guetta <daniel@guetta.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: openai>=1.66.2
+Requires-Dist: requests>=2.32.2
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+# cached_openai
+
+`cached_openai` is a simple Python library that mimics the `OpenAI` python library, but can draw from a cache instead of sending the request to Open AI.
+
+When it is run in **dev mode**, it caches responses to all requests made from OpenAI, and returns the cached value if the request is made again. When it is run in **production mode**, no new cache entries are created, but if any requests stored in the cache are made again, they are returned therefrom.
+
+It is able to cache several different responses for a single request, to mimic the way the OpenAI API returns different responses when it receives the same query twice. It is also able to handle requests that return images or sound clips.
+
+The user experience with `cached_open` is identical to that with the original `openai` package. Consider, for example, the following piece of code using the "regular" `openai` api:
+```
+import openai
+client = openai.OpenAI(api_key=...)
+response = client.chat.completions.create(...)
+```
+
+In `cached_openai`, the **only** change required would be to change the first line to `import cached_openai as openai`. That's it - everything else works identically. If the query is cached, the cached version will be returned. If not, the `OpenAI` API will be queries as usual.
+
+The package can be configured to return the cached entry immediately, *or* to replicate the delay that would occur if the request were to be made from OpenAI directly.
+
+The package also works with the async version of the OpenAI API - just use `openai.AsyncOpenAI(...)`.
+
+## Why `cached_openai`?
+
+I designed this package for teaching purposes - when I teach classes that use the OpenAI API, I often provide code to students which they run on their machines before modifying it. This isn't ideal for two reasons
+  1. Every student has to pay to run the API requests in the code - there can be hundreds or thousands of these requests, and the costs can add up.
+  2. Every student is likely to get different answers out of the API - it makes it difficult to teach the class when everyone is looking at a different answer.
+
+Instead, I can now distributed `cached_openai` with a cache I prepared - students can then run the entire code for free, and get the same answers as I did. They can then modify the code to run their own version, and query OpenAI as usual.
+
+# User manual
+
+This user manual is divided into two parts - preparing a cache, and distributing it.
+
+## Preparing a cache
+
+To prepare a cache, you need to run `cached_openai` in **dev mode**. To do this, set an environment variable called `CACHED_OPENAI_DEV_MODE` to any value before you load the package. I also recommended you set an environment variable called `CACHED_OPENAI_VERBOSE` to any value to print debugging messages as the package runs. The easiest way too do this is in your code, before you import the package
+
+```
+import os
+os.environ['CACHED_OPENAI_VERBOSE'] = 'True'
+os.environ['CACHED_OPENAI_DEV_MODE'] = 'True'
+import cached_openai
+```
+
+You should then use `cached_openai` exactly as you would `OpenAI` - every request you make will be cached. In dev mode, the package creates three files in your working directory
+  - `openai_cache_temp.bin` is a temporary cache file - it is updated every time a call is made to the OpenAI API to store the results of that call. It can be updated very quickly (so as not to slow down the call), but stores data in an inneficient format.
+  - `openai_cache.cache` is the main cache file which contains all cached requests in an efficient format (a dictionary). Every time the package is loaded, the data in `openai_cache_temp.bin` is integrated into this permanent cache file, and the temporary file is deleted.
+  - `openai_cache_used.txt` stores all the keys of requests that have been made or saved since the file was last created; we'll explain the purpose of this file later.
+
+### Determining delays
+
+The package can be configured to return the cached entry immediately, *or* to replicate the delay that would occur if the request were to be made from OpenAI directly.
+
+By default, the package will be configured to return the result immediately. If you would, instead, like it to replicate the delay that was initially observed when the request was made, simply set an environment variable called `CACHED_OPENAI_DELAY_RESPONSES` to any value before you load the package.
+
+### Repeated requests
+
+When you use `cached_openai` to run a request that has already been run, a new request will not be made to OpenAI - the *cached* result is returned instead, for free.
+
+This does mean, however, that that result will be the same every time. What if you want to store several different responses to a single request? All you need to do is provide a `seed` parameter when you run that same request - if the function has been run with that identical seed before, that result is returned, but if not, the query is run again against the OpenAI API. If the underlying OpenAI API function has a seed parameter (eg: `chat.completions.create`), the seed is passed to that function, and if not (eg: `audio.speech.create`), it is stripped before it is sent.
+
+When the request is next called *without* a seed, it will return each of the seeded responses in succession, which will make it look like it is returning different results every time, just like the original API. Here's an example that might clarify this, using chat completions:
+
+  - **Input**: please give me a random number. **Output**: 42
+    - *This is the first time the request has been made, so it is sent to the OpenAI API.*\
+  - **Input**: please give me a random number (`seed=1`). **Output**: 25
+    - *This is the first time the request has been made with this seed, so it is sent to the OpenAI API.*
+  - **Input**: please give me a random number (`seed=2`). **Output**: 126
+    - *This is the first time the request has been made with this seed, so it is sent to the OpenAI API.*
+  - **Input**: please give me a random number (`seed=2`). **Output**: 126
+    - *This request has been made with this seed before, the cached result is returned*
+  - **Input**: please give me a random number. **Output**: 42
+    - *This request has been made before and is being called again for the first time; return the first saved response.*
+  - **Input**: please give me a random number. **Output**: 25
+    - *This request has been made before and is being called again for the second time; return the second saved response.*
+  - **Input**: please give me a random number. **Output**: 126
+    - *This request has been made before and is being called again for the third time; return the third saved response.*
+  - **Input**: please give me a random number. **Output**: 42
+    - *This request has been made before and is being called again for the four time; there is no fourth response stored, so loop back to the first stored answer.*
+
+### Images
+
+Image requests that return image URLs require specific handling, because OpenAI does not keep these image URLs active forever - they are deleted a few hours after the request is made. Thus, simply storing the original response with the original URL would return a broken link when the cached response was returned.
+
+To solve this problem, `cached_openai` downloads the image from the URL before returning the result, and stores it in the cache. When the same request is later called and retrieved from the cache, the image is extracted into an `image` folder in the working directory, and the URLs in the response are replaced with local URLs pointing to those extracted images.
+
+### Audio
+
+Audio requests suffer from a similar problem - OpenAI returns a file stream which then needs to be downloaded. `cached_openai` handles this seamlessly by downloading the file at request time, saving it in the cache, and simulating a file stream when the request is called again and needs to be retrieved from the cache.
+
+## Distributing the cache
+
+Once you have created the cache for your class, there are three different ways to distribute it to students
+  - Get students to install `cached_openai` directly from pypi, and distribute a cache file that they can put in their working directory containing the cache data; you can also publish this file to a URL and `cached_openai` will ask them for a URL from which to download (and potentially decompress) the file.
+  - Create your own package on pypi that forks `cached_openai` and includes your own cache file in it (note that this only works if your cache file is small enough to be uploaded to pypi).
+  - Create a self-contained `.py` file that contains not only the `cached_openai` code, but also the cache itself, embedded in the file. You can then simply distribute this `.py` file as a "batteries included" package.
+
+In all three cases, the first step is to call the `materialize` function, which will package the cache for you; see the function docstring for details.

cached_openai-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+cached_openai/__init__.py,sha256=DpcHHIIjEG1X5L1x6Mul3Lu4aPIWRHnEXz61SlOTR4w,336
+cached_openai/cached_client.py,sha256=jD-L5d9OrDBK7--iUJiGY2wtXTfeECY00_Aq6WzpKzI,19597
+cached_openai/main.py,sha256=2UJKySQRNVYD6bidfUvZNPIjWD7bV5CMOj8BwrKkINE,7835
+cached_openai/materialize_utils.py,sha256=NJAihG7KfqoNcS2cpmeRMvPIQY-dR0HY6DRotAlhuEo,4923
+cached_openai/utils.py,sha256=PzdvQsp_HD2fjUgl3tE49wZ07UAD-gsCIAkylsDJY-Q,7409
+cached_openai-0.0.1.dist-info/METADATA,sha256=qjuKwAelc27wpbJjhPMSwkA7cXp_87upSXNrVfE9d84,9519
+cached_openai-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cached_openai-0.0.1.dist-info/licenses/LICENSE,sha256=_ANFpoG5LuiFv1tOVgx6DB05ngEHADp7aahMVcf_sWs,1060
+cached_openai-0.0.1.dist-info/RECORD,,

cached_openai-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cached_openai-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Daniel Guetta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.