Improve SemanticCache for metadata persistence (#97)

This PR improves the ability to store optional metadata alongside
entries in the `SemanticCache`. It also improves documentation,
docstrings, comments, and user guide examples for the cache.

Author: tylerhutcherson

docs/api/cache.rst

@@ -15,9 +15,10 @@ SemanticCache
     SemanticCache.__init__
     SemanticCache.check
     SemanticCache.store
-    SemanticCache.set_threshold
+    SemanticCache.clear
+    SemanticCache.delete
     SemanticCache.distance_threshold
-    SemanticCache.index
+    SemanticCache.set_threshold
     SemanticCache.ttl
     SemanticCache.set_ttl
 

docs/user_guide/llmcache_03.ipynb

@@ -65,7 +65,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Initializing and using ``SemanticCache``\n",
+    "## Initializing ``SemanticCache``\n",
     "\n",
     "``SemanticCache`` will automatically create an index within Redis upon initialization for the semantic cache content."
    ]
@@ -80,9 +80,9 @@
     "\n",
     "llmcache = SemanticCache(\n",
     "    name=\"llmcache\",                     # underlying search index name\n",
-    "    prefix=\"llmcache\",                   # redis key prefix\n",
+    "    prefix=\"llmcache\",                   # redis key prefix for hash entries\n",
     "    redis_url=\"redis://localhost:6379\",  # redis connection url string\n",
-    "    distance_threshold=0.1               # semantic distance threshold\n",
+    "    distance_threshold=0.1               # semantic cache distance threshold\n",
     ")"
    ]
   },
@@ -119,6 +119,13 @@
     "!rvl index info -i llmcache"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Basic Cache Usage"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 5,
@@ -134,99 +141,89 @@
    "metadata": {},
    "outputs": [
     {
-     "data": {
-      "text/plain": [
-       "[]"
-      ]
-     },
-     "execution_count": 6,
-     "metadata": {},
-     "output_type": "execute_result"
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Empty cache\n"
+     ]
     }
    ],
    "source": [
-    "# Check the cache -- should be empty\n",
-    "llmcache.check(prompt=question)"
+    "# Check the semantic cache -- should be empty\n",
+    "if response := llmcache.check(prompt=question):\n",
+    "    print(response)\n",
+    "else:\n",
+    "    print(\"Empty cache\")"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 7,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "# Cache the question and answer\n",
-    "llmcache.store(prompt=question, response=\"Paris\")"
+    "Our initial cache check should be empty since we have not yet stored anything in the cache. Below, store the `question`,\n",
+    "proper `response`, and any arbitrary `metadata` (as a python dictionary object) in the cache."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 7,
    "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "[{'response': 'Paris', 'vector_distance': '8.34465026855e-07'}]"
-      ]
-     },
-     "execution_count": 8,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
    "source": [
-    "# Check the cache again to see if new answer is there\n",
-    "llmcache.check(prompt=question)"
+    "# Cache the question, answer, and arbitrary metadata\n",
+    "llmcache.store(\n",
+    "    prompt=question,\n",
+    "    response=\"Paris\",\n",
+    "    metadata={\"city\": \"Paris\", \"country\": \"france\"}\n",
+    ")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
-     "data": {
-      "text/plain": [
-       "[{'response': 'Paris',\n",
-       "  'prompt': 'What is the capital of France?',\n",
-       "  'vector_distance': '8.34465026855e-07'}]"
-      ]
-     },
-     "execution_count": 9,
-     "metadata": {},
-     "output_type": "execute_result"
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[{'id': 'llmcache:115049a298532be2f181edb03f766770c0db84c22aff39003fec340deaec7545', 'vector_distance': '8.34465026855e-07', 'prompt': 'What is the capital of France?', 'response': 'Paris', 'metadata': {'city': 'Paris', 'country': 'france'}}]\n"
+     ]
     }
    ],
    "source": [
-    "# Update the return fields to gather other kinds of information about the cached entity\n",
-    "llmcache.check(prompt=question, return_fields=[\"response\", \"prompt\"])"
+    "# Check the cache again\n",
+    "if response := llmcache.check(prompt=question, return_fields=[\"prompt\", \"response\", \"metadata\"]):\n",
+    "    print(response)\n",
+    "else:\n",
+    "    print(\"Empty cache\")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[{'response': 'Paris', 'vector_distance': '0.0988066792488'}]"
+       "'Paris'"
       ]
      },
-     "execution_count": 10,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "# Check for a semantically similar result\n",
-    "llmcache.check(prompt=\"What actually is the capital of France?\")"
+    "question = \"What actually is the capital of France?\"\n",
+    "llmcache.check(prompt=question)[0]['response']"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -236,41 +233,30 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[{'response': 'Paris', 'vector_distance': '0.273138523102'}]"
+       "'Paris'"
       ]
      },
-     "execution_count": 12,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "# Really try to trick it by asking around the point\n",
     "# But is able to slip just under our new threshold\n",
-    "llmcache.check(\n",
-    "    prompt=\"What is the capital city of the country in Europe that also has a city named Nice?\"\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 13,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Invalidate the cache completely by clearing it out\n",
-    "llmcache.clear()"
+    "question = \"What is the capital city of the country in Europe that also has a city named Nice?\"\n",
+    "llmcache.check(prompt=question)[0]['response']"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [
     {
@@ -279,12 +265,15 @@
        "[]"
       ]
      },
-     "execution_count": 14,
+     "execution_count": 12,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
+    "# Invalidate the cache completely by clearing it out\n",
+    "llmcache.clear()\n",
+    "\n",
     "# should be empty now\n",
     "llmcache.check(prompt=question)"
    ]
@@ -300,7 +289,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 13,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -327,14 +316,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Without caching, a call to openAI to answer this simple question took 0.5083951950073242 seconds.\n"
+      "Without caching, a call to openAI to answer this simple question took 0.5017588138580322 seconds.\n"
      ]
     }
    ],
@@ -349,7 +338,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 15,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -358,15 +347,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 34,
+   "execution_count": 16,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Time Taken with cache enabled: 0.08954691886901855\n",
-      "Percentage of time saved: 82.39%\n"
+      "Time Taken with cache enabled: 0.327639102935791\n",
+      "Percentage of time saved: 34.7%\n"
      ]
     }
    ],
@@ -380,7 +369,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 35,
+   "execution_count": 17,
    "metadata": {},
    "outputs": [
     {
@@ -398,7 +387,7 @@
       "│ num_records                 │ 16          │\n",
       "│ percent_indexed             │ 1           │\n",
       "│ hash_indexing_failures      │ 0           │\n",
-      "│ number_of_uses              │ 26          │\n",
+      "│ number_of_uses              │ 9           │\n",
       "│ bytes_per_record_avg        │ 5.25        │\n",
       "│ doc_table_size_mb           │ 0.000134468 │\n",
       "│ inverted_sz_mb              │ 8.01086e-05 │\n",
@@ -408,7 +397,7 @@
       "│ offsets_per_term_avg        │ 0.875       │\n",
       "│ records_per_doc_avg         │ 16          │\n",
       "│ sortable_values_size_mb     │ 0           │\n",
-      "│ total_indexing_time         │ 0.76        │\n",
+      "│ total_indexing_time         │ 0.548       │\n",
       "│ total_inverted_index_blocks │ 7           │\n",
       "│ vector_index_sz_mb          │ 3.0161      │\n",
       "╰─────────────────────────────┴─────────────╯\n"
@@ -422,15 +411,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 18,
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Clear the cache\n",
-    "llmcache.clear()\n",
-    "\n",
-    "# Remove the underlying index\n",
-    "llmcache._index.delete(drop=True)"
+    "# Clear the cache AND delete the underlying index\n",
+    "llmcache.delete()"
    ]
   }
  ],