diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf134632..ef262d75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ Here's how to get started with your code contribution: ### Prerequisites -- **Python**: RedisVL supports Python 3.8 and above +- **Python**: RedisVL supports Python 3.9 and above - **Docker**: Required for running Redis Stack and integration tests - **UV**: Modern Python package manager for fast dependency management @@ -135,8 +135,8 @@ make lint You can also run these commands directly with UV: ```bash -uv run ruff format -uv run ruff check --fix +uv run isort ./redisvl ./tests/ --profile black +uv run black ./redisvl ./tests/ uv run mypy redisvl ``` diff --git a/docs/user_guide/01_getting_started.ipynb b/docs/user_guide/01_getting_started.ipynb index e9313a0f..0d181243 100644 --- a/docs/user_guide/01_getting_started.ipynb +++ b/docs/user_guide/01_getting_started.ipynb @@ -14,8 +14,9 @@ "3. Creating a `SearchIndex`\n", "4. Using the `rvl` CLI\n", "5. Loading data into Redis\n", - "6. Executing vector searches\n", - "7. Updating an index\n", + "6. Fetching and managing records\n", + "7. Executing vector searches\n", + "8. Updating an index\n", "\n", "## Prerequisites\n", "\n", @@ -30,6 +31,8 @@ "- Build and manage `SearchIndex` objects\n", "- Use the `rvl` CLI for index management\n", "- Load data and execute vector similarity searches\n", + "- Fetch individual records and list all keys in an index\n", + "- Delete specific records by key or document ID\n", "- Update index schemas as your application evolves" ] }, @@ -469,14 +472,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Creating `VectorQuery` Objects\n", + "## Fetch and Manage Records\n", "\n", - "Next we will create a vector query object for our newly populated index. This example will use a simple vector to demonstrate how vector similarity works. Vectors in production will likely be much larger than 3 floats and often require Machine Learning models (i.e. Huggingface sentence transformers) or an embeddings API (Cohere, OpenAI). `redisvl` provides a set of [Vectorizers](https://docs.redisvl.com/en/latest/user_guide/vectorizers_04.html#openai) to assist in vector creation." + "RedisVL provides several methods to retrieve and manage individual records in your index." ] }, { - "cell_type": "code", - "execution_count": 13, + "cell_type": "markdown", "metadata": { "execution": { "iopub.execute_input": "2026-02-16T15:11:25.747124Z", @@ -485,46 +487,31 @@ "shell.execute_reply": "2026-02-16T15:11:25.749218Z" } }, - "outputs": [], "source": [ - "from redisvl.query import VectorQuery\n", - "from jupyterutils import result_print\n", + "### Fetch a record by ID\n", "\n", - "query = VectorQuery(\n", - " vector=[0.1, 0.1, 0.5],\n", - " vector_field_name=\"user_embedding\",\n", - " return_fields=[\"user\", \"age\", \"job\", \"credit_score\", \"vector_distance\"],\n", - " num_results=3\n", - ")" + "Use `fetch()` to retrieve a single record when you know its ID. The ID is the unique identifier you provided during load (via `id_field`) or the auto-generated ULID." ] }, { - "cell_type": "markdown", + "cell_type": "code", "metadata": {}, "source": [ - "**Note:** For HNSW and SVS-VAMANA indexes, you can tune search performance using runtime parameters:\n", - "\n", - "```python\n", - "# Example with HNSW runtime parameters\n", - "query = VectorQuery(\n", - " vector=[0.1, 0.1, 0.5],\n", - " vector_field_name=\"user_embedding\",\n", - " return_fields=[\"user\", \"age\", \"job\"],\n", - " num_results=3,\n", - " ef_runtime=50 # Higher for better recall (HNSW only)\n", - ")\n", - "```\n", + "# Fetch a record by its ID (e.g., the user field value if used as id_field)\n", + "# First, let's reload data with a specific id_field\n", + "index.load(data, id_field=\"user\")\n", "\n", - "See the [SVS-VAMANA guide](09_svs_vamana.ipynb) and [Advanced Queries guide](11_advanced_queries.ipynb) for more details on runtime parameters." - ] + "# Now fetch by the user ID\n", + "record = index.fetch(\"john\")\n", + "print(record)" + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": [ - "### Executing queries\n", - "With our `VectorQuery` object defined above, we can execute the query over the `SearchIndex` using the `query` method." - ] + "source": "You can also construct the full Redis key from an ID using the `key()` method:" }, { "cell_type": "code", @@ -552,18 +539,18 @@ } ], "source": [ - "results = index.query(query)\n", - "result_print(results)" + "# Get the full Redis key for a given ID\n", + "full_key = index.key(\"john\")\n", + "print(f\"Full Redis key: {full_key}\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Using an Asynchronous Redis Client\n", + "### List all keys in the index\n", "\n", - "The `AsyncSearchIndex` class along with an async Redis python client allows for queries, index creation, and data loading to be done asynchronously. This is the\n", - "recommended route for working with `redisvl` in production-like settings." + "To enumerate all keys in your index, use `paginate()` with a `FilterQuery`. This is useful for batch processing or auditing your data." ] }, { @@ -579,16 +566,23 @@ }, "outputs": [], "source": [ - "from redisvl.index import AsyncSearchIndex\n", - "from redis.asyncio import Redis\n", + "from redisvl.query import FilterQuery\n", + "from redisvl.query.filter import FilterExpression\n", "\n", - "client = Redis.from_url(\"redis://localhost:6379\")\n", - "index = AsyncSearchIndex.from_dict(schema, redis_client=client)" + "# Create a query that matches all documents\n", + "query = FilterQuery(\n", + " filter_expression=FilterExpression(\"*\"),\n", + " return_fields=[\"user\", \"age\", \"job\"]\n", + ")\n", + "\n", + "# Paginate through all results\n", + "for batch in index.paginate(query, page_size=10):\n", + " for doc in batch:\n", + " print(f\"Key: {doc['id']}, User: {doc['user']}\")" ] }, { - "cell_type": "code", - "execution_count": 16, + "cell_type": "markdown", "metadata": { "execution": { "iopub.execute_input": "2026-02-16T15:11:25.763219Z", @@ -597,46 +591,43 @@ "shell.execute_reply": "2026-02-16T15:11:25.769135Z" } }, - "outputs": [ - { - "data": { - "text/html": [ - "
vector_distanceuseragejobcredit_score
0john1engineerhigh
0mary2doctorlow
0.0566298961639tyler9engineerhigh
" - ], - "text/plain": [ - "" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], "source": [ - "# execute the vector query async\n", - "results = await index.query(query)\n", - "result_print(results)" + "### Delete specific records\n", + "\n", + "Use `drop_keys()` to remove specific records by their full Redis key, or `drop_documents()` to remove by document ID." ] }, { - "cell_type": "markdown", + "cell_type": "code", "metadata": {}, "source": [ - "## Updating a schema\n", - "In some scenarios, it makes sense to update the index schema. With Redis and `redisvl`, this is easy because Redis can keep the underlying data in place while you change or make updates to the index configuration." - ] + "# Delete by full Redis key\n", + "full_key = index.key(\"john\")\n", + "deleted_count = index.drop_keys(full_key)\n", + "print(f\"Deleted {deleted_count} record(s) by key\")\n", + "\n", + "# Delete multiple keys at once\n", + "# index.drop_keys([\"key1\", \"key2\", \"key3\"])" + ], + "outputs": [], + "execution_count": null }, { - "cell_type": "markdown", + "cell_type": "code", "metadata": {}, "source": [ - "So for our scenario, let's imagine we want to reindex this data in 2 ways:\n", - "- by using a `Tag` type for `job` field instead of `Text`\n", - "- by using an `hnsw` vector index for the `user_embedding` field instead of a `flat` vector index" - ] + "# Delete by document ID (without the prefix)\n", + "deleted_count = index.drop_documents(\"mary\")\n", + "print(f\"Deleted {deleted_count} record(s) by document ID\")\n", + "\n", + "# Delete multiple documents at once\n", + "# index.drop_documents([\"id1\", \"id2\", \"id3\"])" + ], + "outputs": [], + "execution_count": null }, { - "cell_type": "code", - "execution_count": 17, + "cell_type": "markdown", "metadata": { "execution": { "iopub.execute_input": "2026-02-16T15:11:25.770560Z", @@ -645,29 +636,10 @@ "shell.execute_reply": "2026-02-16T15:11:25.772158Z" } }, - "outputs": [], - "source": [ - "# Modify this schema to have what we want\n", - "index.schema.remove_field(\"job\")\n", - "index.schema.remove_field(\"user_embedding\")\n", - "index.schema.add_fields([\n", - " {\"name\": \"job\", \"type\": \"tag\"},\n", - " {\n", - " \"name\": \"user_embedding\",\n", - " \"type\": \"vector\",\n", - " \"attrs\": {\n", - " \"dims\": 3,\n", - " \"distance_metric\": \"cosine\",\n", - " \"algorithm\": \"hnsw\",\n", - " \"datatype\": \"float32\"\n", - " }\n", - " }\n", - "])" - ] + "source": ">**Note:** `drop_keys()` expects the full Redis key (including prefix), while `drop_documents()` expects just the document ID." }, { - "cell_type": "code", - "execution_count": 18, + "cell_type": "markdown", "metadata": { "execution": { "iopub.execute_input": "2026-02-16T15:11:25.773413Z", @@ -676,10 +648,10 @@ "shell.execute_reply": "2026-02-16T15:11:25.780644Z" } }, - "outputs": [], "source": [ - "# Run the index update but keep underlying data in place\n", - "await index.create(overwrite=True, drop=False)" + "## Creating `VectorQuery` Objects\n", + "\n", + "Next we will create a vector query object for our newly populated index. This example will use a simple vector to demonstrate how vector similarity works. Vectors in production will likely be much larger than 3 floats and often require Machine Learning models (i.e. Huggingface sentence transformers) or an embeddings API (Cohere, OpenAI). `redisvl` provides a set of [Vectorizers](https://docs.redisvl.com/en/latest/user_guide/vectorizers_04.html#openai) to assist in vector creation." ] }, { @@ -708,22 +680,39 @@ } ], "source": [ - "# Execute the vector query async\n", - "results = await index.query(query)\n", - "result_print(results)" + "from redisvl.query import VectorQuery\n", + "from jupyterutils import result_print\n", + "\n", + "query = VectorQuery(\n", + " vector=[0.1, 0.1, 0.5],\n", + " vector_field_name=\"user_embedding\",\n", + " return_fields=[\"user\", \"age\", \"job\", \"credit_score\", \"vector_distance\"],\n", + " num_results=3\n", + ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Check Index Stats\n", - "Use the `rvl` CLI to check the stats for the index:" + "**Note:** For HNSW and SVS-VAMANA indexes, you can tune search performance using runtime parameters:\n", + "\n", + "```python\n", + "# Example with HNSW runtime parameters\n", + "query = VectorQuery(\n", + " vector=[0.1, 0.1, 0.5],\n", + " vector_field_name=\"user_embedding\",\n", + " return_fields=[\"user\", \"age\", \"job\"],\n", + " num_results=3,\n", + " ef_runtime=50 # Higher for better recall (HNSW only)\n", + ")\n", + "```\n", + "\n", + "See the [SVS-VAMANA guide](09_svs_vamana.ipynb) and [Advanced Queries guide](11_advanced_queries.ipynb) for more details on runtime parameters." ] }, { - "cell_type": "code", - "execution_count": 20, + "cell_type": "markdown", "metadata": { "execution": { "iopub.execute_input": "2026-02-16T15:11:25.787932Z", @@ -732,65 +721,29 @@ "shell.execute_reply": "2026-02-16T15:11:27.979025Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "\n", - "Statistics:\n", - "╭─────────────────────────────┬────────────╮\n", - "│ Stat Key │ Value │\n", - "├─────────────────────────────┼────────────┤\n", - "│ num_docs │ 4 │\n", - "│ num_terms │ 0 │\n", - "│ max_doc_id │ 4 │\n", - "│ num_records │ 20 │\n", - "│ percent_indexed │ 1 │\n", - "│ hash_indexing_failures │ 0 │\n", - "│ number_of_uses │ 2 │\n", - "│ bytes_per_record_avg │ 45.4500007 │\n", - "│ doc_table_size_mb │ 0.00809097 │\n", - "│ inverted_sz_mb │ 8.66889953 │\n", - "│ key_table_size_mb │ 3.05175781 │\n", - "│ offset_bits_per_record_avg │ nan │\n", - "│ offset_vectors_sz_mb │ 0 │\n", - "│ offsets_per_term_avg │ 0 │\n", - "│ records_per_doc_avg │ 5 │\n", - "│ sortable_values_size_mb │ 0 │\n", - "│ total_indexing_time │ 1.729042 │\n", - "│ total_inverted_index_blocks │ 11 │\n", - "│ vector_index_sz_mb │ 0.23595428 │\n", - "╰─────────────────────────────┴────────────╯\n" - ] - } - ], "source": [ - "!rvl stats -i user_simple" + "### Executing queries\n", + "With our `VectorQuery` object defined above, we can execute the query over the `SearchIndex` using the `query` method." ] }, { - "cell_type": "markdown", + "cell_type": "code", "metadata": {}, "source": [ - "## Next Steps\n", - "\n", - "Now that you understand the basics of RedisVL, explore these related guides:\n", - "\n", - "- [Query and Filter Data](02_complex_filtering.ipynb) - Learn advanced filtering with tag, numeric, text, and geo filters\n", - "- [Create Embeddings with Vectorizers](04_vectorizers.ipynb) - Generate embeddings using OpenAI, HuggingFace, Cohere, and more\n", - "- [Choose a Storage Type](05_hash_vs_json.ipynb) - Understand when to use Hash vs JSON storage" - ] + "results = index.query(query)\n", + "result_print(results)" + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Cleanup\n", - "\n", - "Use `.clear()` to flush all data from Redis associated with the index while leaving the index in place for future insertions.\n", + "## Using an Asynchronous Redis Client\n", "\n", - "Use `.delete()` to remove both the index and the underlying data." + "The `AsyncSearchIndex` class along with an async Redis python client allows for queries, index creation, and data loading to be done asynchronously. This is the\n", + "recommended route for working with `redisvl` in production-like settings." ] }, { @@ -817,8 +770,11 @@ } ], "source": [ - "# Clear all data from Redis associated with the index\n", - "await index.clear()" + "from redisvl.index import AsyncSearchIndex\n", + "from redis.asyncio import Redis\n", + "\n", + "client = Redis.from_url(\"redis://localhost:6379\")\n", + "index = AsyncSearchIndex.from_dict(schema, redis_client=client)" ] }, { @@ -845,13 +801,13 @@ } ], "source": [ - "# But the index is still in place\n", - "await index.exists()" + "# execute the vector query async\n", + "results = await index.query(query)\n", + "result_print(results)" ] }, { - "cell_type": "code", - "execution_count": 23, + "cell_type": "markdown", "metadata": { "execution": { "iopub.execute_input": "2026-02-16T15:11:27.992624Z", @@ -860,7 +816,129 @@ "shell.execute_reply": "2026-02-16T15:11:27.994738Z" } }, + "source": [ + "## Updating a schema\n", + "In some scenarios, it makes sense to update the index schema. With Redis and `redisvl`, this is easy because Redis can keep the underlying data in place while you change or make updates to the index configuration." + ] + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "So for our scenario, let's imagine we want to reindex this data in 2 ways:\n", + "- by using a `Tag` type for `job` field instead of `Text`\n", + "- by using an `hnsw` vector index for the `user_embedding` field instead of a `flat` vector index" + ] + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": [ + "# Modify this schema to have what we want\n", + "index.schema.remove_field(\"job\")\n", + "index.schema.remove_field(\"user_embedding\")\n", + "index.schema.add_fields([\n", + " {\"name\": \"job\", \"type\": \"tag\"},\n", + " {\n", + " \"name\": \"user_embedding\",\n", + " \"type\": \"vector\",\n", + " \"attrs\": {\n", + " \"dims\": 3,\n", + " \"distance_metric\": \"cosine\",\n", + " \"algorithm\": \"hnsw\",\n", + " \"datatype\": \"float32\"\n", + " }\n", + " }\n", + "])" + ] + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": [ + "# Run the index update but keep underlying data in place\n", + "await index.create(overwrite=True, drop=False)" + ] + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": [ + "# Execute the vector query async\n", + "results = await index.query(query)\n", + "result_print(results)" + ] + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "## Check Index Stats\n", + "Use the `rvl` CLI to check the stats for the index:" + ] + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": "!rvl stats -i user_simple" + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "## Next Steps\n", + "\n", + "Now that you understand the basics of RedisVL, explore these related guides:\n", + "\n", + "- [Query and Filter Data](02_complex_filtering.ipynb) - Learn advanced filtering with tag, numeric, text, and geo filters\n", + "- [Create Embeddings with Vectorizers](04_vectorizers.ipynb) - Generate embeddings using OpenAI, HuggingFace, Cohere, and more\n", + "- [Choose a Storage Type](05_hash_vs_json.ipynb) - Understand when to use Hash vs JSON storage" + ] + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "## Cleanup\n", + "\n", + "Use `.clear()` to flush all data from Redis associated with the index while leaving the index in place for future insertions.\n", + "\n", + "Use `.delete()` to remove both the index and the underlying data." + ] + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": [ + "# Clear all data from Redis associated with the index\n", + "await index.clear()" + ] + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": [ + "# But the index is still in place\n", + "await index.exists()" + ] + }, + { + "metadata": {}, + "cell_type": "code", "outputs": [], + "execution_count": null, "source": [ "# Remove / delete the index in its entirety\n", "await index.delete()" diff --git a/docs/user_guide/03_llmcache.ipynb b/docs/user_guide/03_llmcache.ipynb index a8f63039..d32b92a7 100644 --- a/docs/user_guide/03_llmcache.ipynb +++ b/docs/user_guide/03_llmcache.ipynb @@ -20,8 +20,9 @@ "By the end of this guide, you will be able to:\n", "- Set up and configure a `SemanticCache`\n", "- Store and retrieve cached LLM responses\n", + "- Understand entry IDs and keys for fetching and deleting specific entries\n", "- Customize semantic similarity thresholds\n", - "- Configure TTL policies for cache expiration\n", + "- Configure TTL policies and understand TTL refresh behavior\n", "- Implement access controls with tags and filters for multi-user scenarios" ] }, @@ -36,11 +37,15 @@ "cell_type": "code", "execution_count": 1, "metadata": { + "ExecuteTime": { + "end_time": "2026-03-02T22:25:45.034564Z", + "start_time": "2026-03-02T22:25:44.931595Z" + }, "execution": { - "iopub.execute_input": "2026-02-16T15:30:03.699360Z", - "iopub.status.busy": "2026-02-16T15:30:03.699221Z", - "iopub.status.idle": "2026-02-16T15:30:04.311512Z", - "shell.execute_reply": "2026-02-16T15:30:04.310977Z" + "iopub.execute_input": "2026-03-02T22:27:10.449512Z", + "iopub.status.busy": "2026-03-02T22:27:10.449369Z", + "iopub.status.idle": "2026-03-02T22:27:10.804323Z", + "shell.execute_reply": "2026-03-02T22:27:10.803899Z" } }, "outputs": [], @@ -73,10 +78,10 @@ "execution_count": 2, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:04.312736Z", - "iopub.status.busy": "2026-02-16T15:30:04.312623Z", - "iopub.status.idle": "2026-02-16T15:30:11.559321Z", - "shell.execute_reply": "2026-02-16T15:30:11.558753Z" + "iopub.execute_input": "2026-03-02T22:27:10.805934Z", + "iopub.status.busy": "2026-03-02T22:27:10.805825Z", + "iopub.status.idle": "2026-03-02T22:27:11.717663Z", + "shell.execute_reply": "2026-03-02T22:27:11.716983Z" } }, "outputs": [ @@ -84,7 +89,9 @@ "name": "stdout", "output_type": "stream", "text": [ - "The capital of France is Paris.\n" + "**\n", + "\n", + "Paris.\n" ] } ], @@ -104,13 +111,17 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, "metadata": { + "ExecuteTime": { + "end_time": "2026-03-02T22:15:06.103275Z", + "start_time": "2026-03-02T22:15:05.788252Z" + }, "execution": { - "iopub.execute_input": "2026-02-16T15:30:11.583737Z", - "iopub.status.busy": "2026-02-16T15:30:11.583617Z", - "iopub.status.idle": "2026-02-16T15:30:31.793657Z", - "shell.execute_reply": "2026-02-16T15:30:31.793174Z" + "iopub.execute_input": "2026-03-02T22:27:11.742127Z", + "iopub.status.busy": "2026-03-02T22:27:11.741989Z", + "iopub.status.idle": "2026-03-02T22:27:18.650656Z", + "shell.execute_reply": "2026-03-02T22:27:18.650073Z" } }, "outputs": [], @@ -125,7 +136,7 @@ " name=\"llmcache\", # underlying search index name\n", " redis_url=\"redis://localhost:6379\", # redis connection url string\n", " distance_threshold=0.1, # semantic cache distance threshold (Redis COSINE [0-2], lower is stricter)\n", - " vectorizer=HFTextVectorizer(\"redis/langcache-embed-v1\"), # embedding model\n", + " vectorizer=HFTextVectorizer(\"redis/langcache-embed-v2\"), # embedding model\n", ")" ] }, @@ -134,10 +145,10 @@ "execution_count": 4, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:31.795376Z", - "iopub.status.busy": "2026-02-16T15:30:31.795045Z", - "iopub.status.idle": "2026-02-16T15:30:34.018783Z", - "shell.execute_reply": "2026-02-16T15:30:34.018106Z" + "iopub.execute_input": "2026-03-02T22:27:18.652846Z", + "iopub.status.busy": "2026-03-02T22:27:18.652367Z", + "iopub.status.idle": "2026-03-02T22:27:19.025560Z", + "shell.execute_reply": "2026-03-02T22:27:19.024938Z" } }, "outputs": [ @@ -145,24 +156,24 @@ "name": "stdout", "output_type": "stream", "text": [ - "\n", - "\n", - "Index Information:\n", - "╭───────────────┬───────────────┬───────────────┬───────────────┬───────────────╮\n", - "│ Index Name │ Storage Type │ Prefixes │ Index Options │ Indexing │\n", - "├───────────────┼───────────────┼───────────────┼───────────────┼───────────────┤\n", - "| llmcache | HASH | ['llmcache'] | [] | 0 |\n", - "╰───────────────┴───────────────┴───────────────┴───────────────┴───────────────╯\n", - "Index Fields:\n", - "╭─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────╮\n", - "│ Name │ Attribute │ Type │ Field Option │ Option Value │ Field Option │ Option Value │ Field Option │ Option Value │ Field Option │ Option Value │\n", - "├─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┤\n", - "│ prompt │ prompt │ TEXT │ WEIGHT │ 1 │ │ │ │ │ │ │\n", - "│ response │ response │ TEXT │ WEIGHT │ 1 │ │ │ │ │ │ │\n", - "│ inserted_at │ inserted_at │ NUMERIC │ │ │ │ │ │ │ │ │\n", - "│ updated_at │ updated_at │ NUMERIC │ │ │ │ │ │ │ │ │\n", - "│ prompt_vector │ prompt_vector │ VECTOR │ algorithm │ FLAT │ data_type │ FLOAT32 │ dim │ 768 │ distance_metric │ COSINE │\n", - "╰─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────╯\n" + "\r\n", + "\r\n", + "Index Information:\r\n", + "\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\b\u256e\r\n", + "\u2502 Index Name \u2502 Storage Type \u2502 Prefixes \u2502 Index Options \u2502 Indexing \u2502\r\n", + "\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\b\u2524\r\n", + "| llmcache | HASH | ['llmcache'] | [] | 0 |\r\n", + "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\b\u256f\r\n", + "Index Fields:\r\n", + "\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\b\u256e\r\n", + "\u2502 Name \u2502 Attribute \u2502 Type \u2502 Field Option \u2502 Option Value \u2502 Field Option \u2502 Option Value \u2502 Field Option \u2502 Option Value \u2502 Field Option \u2502 Option Value \u2502\r\n", + "\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\b\u2524\r\n", + "\u2502 prompt \u2502 prompt \u2502 TEXT \u2502 WEIGHT \u2502 1 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502\r\n", + "\u2502 response \u2502 response \u2502 TEXT \u2502 WEIGHT \u2502 1 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502\r\n", + "\u2502 inserted_at \u2502 inserted_at \u2502 NUMERIC \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502\r\n", + "\u2502 updated_at \u2502 updated_at \u2502 NUMERIC \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502 \u2502\r\n", + "\u2502 prompt_vector \u2502 prompt_vector \u2502 VECTOR \u2502 algorithm \u2502 FLAT \u2502 data_type \u2502 FLOAT32 \u2502 dim \u2502 768 \u2502 distance_metric \u2502 COSINE \u2502\r\n", + "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\b\u256f\r\n" ] } ], @@ -183,10 +194,10 @@ "execution_count": 5, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.020632Z", - "iopub.status.busy": "2026-02-16T15:30:34.020490Z", - "iopub.status.idle": "2026-02-16T15:30:34.022884Z", - "shell.execute_reply": "2026-02-16T15:30:34.022313Z" + "iopub.execute_input": "2026-03-02T22:27:19.027688Z", + "iopub.status.busy": "2026-03-02T22:27:19.027527Z", + "iopub.status.idle": "2026-03-02T22:27:19.029986Z", + "shell.execute_reply": "2026-03-02T22:27:19.029465Z" } }, "outputs": [], @@ -199,10 +210,10 @@ "execution_count": 6, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.024186Z", - "iopub.status.busy": "2026-02-16T15:30:34.024066Z", - "iopub.status.idle": "2026-02-16T15:30:34.142671Z", - "shell.execute_reply": "2026-02-16T15:30:34.142236Z" + "iopub.execute_input": "2026-03-02T22:27:19.031388Z", + "iopub.status.busy": "2026-03-02T22:27:19.031279Z", + "iopub.status.idle": "2026-03-02T22:27:19.081892Z", + "shell.execute_reply": "2026-03-02T22:27:19.081393Z" } }, "outputs": [ @@ -235,10 +246,10 @@ "execution_count": 7, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.144011Z", - "iopub.status.busy": "2026-02-16T15:30:34.143925Z", - "iopub.status.idle": "2026-02-16T15:30:34.186967Z", - "shell.execute_reply": "2026-02-16T15:30:34.186507Z" + "iopub.execute_input": "2026-03-02T22:27:19.083173Z", + "iopub.status.busy": "2026-03-02T22:27:19.083085Z", + "iopub.status.idle": "2026-03-02T22:27:19.099174Z", + "shell.execute_reply": "2026-03-02T22:27:19.098836Z" } }, "outputs": [ @@ -274,10 +285,10 @@ "execution_count": 8, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.188029Z", - "iopub.status.busy": "2026-02-16T15:30:34.187942Z", - "iopub.status.idle": "2026-02-16T15:30:34.229841Z", - "shell.execute_reply": "2026-02-16T15:30:34.229399Z" + "iopub.execute_input": "2026-03-02T22:27:19.100460Z", + "iopub.status.busy": "2026-03-02T22:27:19.100378Z", + "iopub.status.idle": "2026-03-02T22:27:19.114401Z", + "shell.execute_reply": "2026-03-02T22:27:19.114112Z" } }, "outputs": [ @@ -302,10 +313,10 @@ "execution_count": 9, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.230921Z", - "iopub.status.busy": "2026-02-16T15:30:34.230847Z", - "iopub.status.idle": "2026-02-16T15:30:34.338748Z", - "shell.execute_reply": "2026-02-16T15:30:34.338236Z" + "iopub.execute_input": "2026-03-02T22:27:19.115602Z", + "iopub.status.busy": "2026-03-02T22:27:19.115523Z", + "iopub.status.idle": "2026-03-02T22:27:19.150468Z", + "shell.execute_reply": "2026-03-02T22:27:19.150073Z" } }, "outputs": [ @@ -329,6 +340,195 @@ { "cell_type": "markdown", "metadata": {}, + "source": [ + "## Entry IDs and Keys\n", + "\n", + "Each cache entry has two identifiers:\n", + "\n", + "- **`entry_id`**: A deterministic hash of the prompt + filters. Used to identify the entry within the cache.\n", + "- **`key`**: The full Redis key (prefix + entry_id). Used for direct Redis operations.\n", + "\n", + "The `entry_id` is generated as a SHA256 hash of the prompt and any filters, meaning:\n", + "- Same prompt + same filters = same `entry_id` (overwrites previous entry)\n", + "- Same prompt + different filters = different `entry_id` (both stored)" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": { + "execution": { + "iopub.execute_input": "2026-03-02T22:27:19.151643Z", + "iopub.status.busy": "2026-03-02T22:27:19.151573Z", + "iopub.status.idle": "2026-03-02T22:27:19.166131Z", + "shell.execute_reply": "2026-03-02T22:27:19.165669Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Full Redis key: llmcache:115049a298532be2f181edb03f766770c0db84c22aff39003fec340deaec7545\n" + ] + } + ], + "source": [ + "# Store an entry and capture the returned key\n", + "key = llmcache.store(\n", + " prompt=\"What is the capital of France?\",\n", + " response=\"Paris\",\n", + " metadata={\"source\": \"geography\"}\n", + ")\n", + "print(f\"Full Redis key: {key}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": { + "execution": { + "iopub.execute_input": "2026-03-02T22:27:19.167141Z", + "iopub.status.busy": "2026-03-02T22:27:19.167076Z", + "iopub.status.idle": "2026-03-02T22:27:19.183016Z", + "shell.execute_reply": "2026-03-02T22:27:19.182705Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Entry ID: 115049a298532be2f181edb03f766770c0db84c22aff39003fec340deaec7545\n", + "Key: llmcache:115049a298532be2f181edb03f766770c0db84c22aff39003fec340deaec7545\n" + ] + } + ], + "source": [ + "# Check and see both entry_id and key in the response\n", + "result = llmcache.check(\n", + " prompt=\"What is the capital of France?\",\n", + " return_fields=[\"entry_id\", \"prompt\", \"response\"]\n", + ")\n", + "print(f\"Entry ID: {result[0]['entry_id']}\")\n", + "print(f\"Key: {result[0]['key']}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Fetch and Delete Specific Entries\n", + "\n", + "You can fetch or delete specific cache entries using the underlying index. First, let's see what keys exist in the cache:" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": { + "execution": { + "iopub.execute_input": "2026-03-02T22:27:19.184270Z", + "iopub.status.busy": "2026-03-02T22:27:19.184202Z", + "iopub.status.idle": "2026-03-02T22:27:19.187243Z", + "shell.execute_reply": "2026-03-02T22:27:19.186964Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Found 1 entries in cache:\n", + " - entry_id: 115049a298532be2f181... prompt: What is the capital of France?...\n" + ] + } + ], + "source": [ + "# List all keys in the cache using the underlying index\n", + "from redisvl.query import FilterQuery\n", + "from redisvl.query.filter import FilterExpression\n", + "\n", + "query = FilterQuery(\n", + " filter_expression=FilterExpression(\"*\"),\n", + " return_fields=[\"entry_id\", \"prompt\", \"response\"]\n", + ")\n", + "all_entries = llmcache._index.query(query)\n", + "print(f\"Found {len(all_entries)} entries in cache:\")\n", + "for entry in all_entries:\n", + " print(f\" - entry_id: {entry['entry_id'][:20]}... prompt: {entry['prompt'][:30]}...\")" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": { + "execution": { + "iopub.execute_input": "2026-03-02T22:27:19.188307Z", + "iopub.status.busy": "2026-03-02T22:27:19.188245Z", + "iopub.status.idle": "2026-03-02T22:27:19.190804Z", + "shell.execute_reply": "2026-03-02T22:27:19.190333Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Fetched record: {'prompt': 'What is the capital of France?', 'prompt_vector': b'\\x80;\\xdb?|\\x0b\\xaa\\xbfj~\\xb7\\xbe\\xd6\\xcdX\\xc0i\\xa6\\xa7?2r\\x12\\xbe\\x81U\\x17\\xc0\\x06jt\\xbf\\xd1M\\x04\\xc0Pd\\x8d\\xc08,\\x17?\\xce\\xef\\x04\\xc0\\x94\\xb2\\x9a\\xbf\\xa2@\\x99\\xbf\\xa1\\xd7\\x8b\\xbeX\\xf4=\\xbf.B\\x1c\\xbf3\\xc2(\\xbf6s\\xdf\\xbd\\x8b\\x9b$\\xbf\\x90\\xab$\\xbfQX}\\xbf-*\\x84\\xbfW\\x02\\r?\\xb1\\xce\\x17\\xc0\\xe6\\xab\\x8a>{l\\xca=\\xc4\\x14\\x9d\\xbe\\x7f,\\x11\\xc0f\\x9b\\xbc=\\xb8;\">$\\x1a\\x1a\\xc0/\\xd0\\x8f?\\xf4\\x02\\x85>\\x10\\x8a\\xc3\\xbe\\xbb-6\\xbb>xm\\xc0Gx\"\\xbf\\x1b@u\\xbd$\\xe9S\\xbe\\x91\\xe55\\xbdR\\x11u@\\x8a\\xab>@\\x9d\\xd7\\xe7?\\'L\\xe0\\xbf\\xfb8;?>\\xce\\x98\\xbf.\\xe0\\xad\\xbez\\xdf\\xdf?\\xbb\\x14\\xaa?\\xf92m\\xbf\\x1e\\x9e\\xde?\\xe9\\xaf\\xf4>\\x91\\x80\\xcd?\\xa1lc\\xbf\\x9a>-?=[q\\xbf\\xfb\\x1at\\xc0\\'\\x1fc?\\x11\\xab\\x83\\xbf\\xee\\xa6&\\xc0+~\\xb8?o\\x14\\xe9\\xbe\\xe3\\xab\\x9c?\\x1e\\xc4K?\\xe7Z\\xa8?\\xe2;\\xbc?\\xb1L\\x9d@\\x9b\\xe9;?:-Y?\\x81<\\\\@i\\xaf\\x9a>\\xf0\\xa3\\x0c;\\x04\\\\\\xb7\\xbf3\\x1a9\\xbf\\xcc?\\x02\\xbf\\xa3\\xf5\\xc8\\xbfV7\"?\\xd9_8\\xc0\\xb0\\x86M?\\xc3\\xda\\x03@\\x9c\\x80\\x95\\xbf\\x8e\\xfa\\xa5?\\x14\\xb1\\x05@z\\xb9n?{\\xc5c\\xc0|z\\x9d>\\x18b\\xa2\\xbe?\\xea\\x17\\xc0@\\xe0\\xa2?\\x98`\\x0c?\\xfak\\xb9\\xbe\\xcdX:?\\xe7,m\\xbf\\n\\x0e@\\xbe\\xb8\\xd8[\\xc0\\xdf\\x1f\\n\\xbf\\xcb\\r\\t\\xbd\\xcb`\\xd6\\xbf\\xad&\\n>\\x19\\x18\\x8f\\xbf\\xf0\\xd5\\x19\\xc0\\xa8\\x81\\xbd\\xbe|\\x10\\x99\\xbf\\x81\\x87\\xe6>`\\xa4\\xcc?U$U\\xbfN\\xb7\\x1a\\xc0x\\xef\\x95>4O\\xa8?\\xa3.\\xf2\\xbe\\x16\\x1d\\r\\xbfw\\x11\\xc6\\xbf.\\x9c\\xd2\\xbe\\xb6\\xfc\\x00@E\\x0b\\x85\\xbenT\\xf4?\\xc26E\\xbeB\\xa4#?\\xe4mV?hX\\xcb?\\xcbzu?\\xfa,\\xf8\\xbfE\\x88\\x8a?\\x04\\x8e\\xc8?\\x92;\\xcf??\\xf3;?\\xec\\xa0\\xc6\\xbf\\x94}u\\xbe\\x11?\\x7f\\xbeA\\xebD?\\t\\xbc\\x8f\\xbe7*\\xa0?8T\\xc4\\xbf&\\x00\\xe3=\\xdd\\xb6\\t>\\xa3\\xea\\xef>\\xf6\\xe3\\n@\\xa5\\xbf\\x80\\xbfA\\xea\\xd7>\\x8df0\\xbf\\xf9 .\\xbf\\x1c.7>D6\\x15?v\\xc7\\x1e\\xbf\\xba\\xdc\\x18\\xbf\\xf57\\xd6?\\x88\\xae\\x03@\\xa9\\xd3\"\\xbe\\x90\\x1cY\\xbe\\xecn\\x8a\\xbeN\\xb9\\x12\\xbf\\x0f\\xe2U>\\xbc\\x06\\xac\\xbf99r\\xbf\\x82U\\xe7\\xbf\\x17(\\xe2\\xbfzk\\xb2=\\xdc\\xf1\\r@\\xbe\\xaf\\xbe\\xbez\\x9d\\xc7?\\x96\\x8a\\xb7\\xbe\\x8e\\xb8=\\xbf<\\xd2a\\xbd7\\xe7\\x11@4:e\\xbf\\xbb\\x9b@\\xbe4\\xa8\\x0c\\xbe\\xe1:\\x9e\\xbe\\xa8\\x8bp\\xbf\\xe2\\x16\\x9d@\\x902M\\xc0*v\\x8f>\\xc5X|\\xbe\\xfe\\xe4\\x84?\\xa8\\x93\\xda\\xbe\\x02\\r\\xfb\\xbfe\\x82\\xfa?\\x17\\x9d\\'\\xc0\\xc1T\\xca\\xbf\\xd3\\xc4\\x8c\\xbe=9\\xf7\\xbez.\\xa4\\xbf!{\\x85\\xbf\\x85/\\xa5=\\xcb\\xe1\\x97?\\nW<\\xbf2v\\xe6\\xbf\\xe2\\xfc\\xd9\\xbc\\x93r\\x1b?\\xba7W=\\xd0/\\r\\xc0J\\xf6;\\xbe\\xdc6\\xba?\\xdd\\xce\\x99\\xbf\\xcf\\xfe\\xe5>\\xe3\\xf6\\r\\xc0n\\xed\\xa9\\xbfn\\x9c\\x1a?\\xe8\\x0f\\x92\\xbd\\xb0y\\x0b@O\\xf8\\x90?rq+\\xc0\\xb3\\xa7=?\\xfdl\\xc3\\xbf\\xd6Z\\x01?Z\\xd69\\xbf\\x1c\\x06\\xba?\\xfc\\\\\\x96\\xbf\\x91\\xee\\xe9?\\xbf\\xc5\\xda>W\\xed\\x97?\\x1d\\xc4\\x0c?\\x15\\x93\\xbb?\\x8d\\xaf\\x87\\xc0\\x06{D\\xbeK\\xb9\\xdb?a\\x19}\\xbf_(9\\xbf\\xecL\\'@\\xa2\\xc2\\xdd?\\x06\\x86\\xc8\\xbe\\x94N\\x1a\\xc0\\x9c\\x13\\xce>\\xab\\x9ae\\xbfC\\xf6\\xde\\xbem\\n\\xce\\xbe\\x17\\xd5\\x04@5Mf\\xbe\\xf4\\xea\\x8d?\\xb4\\xa2=\\xbf>\\xbc\\x1a\\xc0\\x01H\\x93?*X\\x87?|6\\xa4?\\xa5`\\xbc\\xbe~L\\xa7>\\xa5@\\x95\\xbeZo\\x8a\\xbf\\x10\\xec\\x8d\\xbee\\xe3+@\\xd3\\xd8\\xa2\\xbf\\xf6+\\xacG.\\xc0\\xc0\\x13\\xaa?D\\xea\"?\\xa5\\xc5\\xb3?\\xbe\\x12\\xa4?\\xea<\\x19@\\x92X\\xd0?\\x8c\\xa9i\\xbf\\xb8I\\x1d?\\x19\\xca\\xf8?L\\x0c\\x85>\\xdcd\\xb8\\xbf\\xda@v\\xbd4\\xb3\\xf9\\xbf\\xa6\\x80\\x83\\x94=\\x07\\xc0\\xef>\\r@ \\x9b\\x95?4\\x803\\xbf1\\r\\xf3?>v>>\\x1cx\\xc9>Au2@\\x98n$@\\x8e\\xa9O\\xbf#S6=\\xf6G9?\\xc6;\\x81\\xbf$w\\xd7?\\x11\\x89L\\xbf\\xb7\\x1f\\xec;\\x8e\\xab\\x06\\xc0\\xba\\x16\\xb2\\xbe0\\xa8\\'\\xc0\\xf4\\x17j?\\x84\\xd7\\xa5?,\\xe7\\xd0\\xbe\\xa7\\xd6\\xea?\\xc5\\xec\\xfa?\\xdaa\\xee?#\\x07\\xe8\\xbe\\xed\\xda\\xe7;jC\\xac\\xbf\\x17\\xc1f?\\xedx|\\xbe\\xe6\\x1d\\xd5\\xbf\\xb6;$\\xc0\\xe0\\xdd\\xc9\\xbcGN\\x07\\xc0J;\\x08\\xc0\\x85\\xfa}\\xbf\\x04\\xc7]?\\xaa\\x8b\\xd2?\\xc7\\x01\\xa9?\\x80\\xac\\x0c@gG\\x94?\\xf7S\\xa1?\\xe2\\xb2\\xc2\\xbf\\x9aD\\x01@\\r\\xac\\xf8?\\x8f\\xcf\\xe4\\xbe\\xc22]\\xbe\\x0fU\\xab\\xbe\\x8b\\x80\\xdf>T\\xb5V\\xbfy\\x7f\\xc0?y\\x10\\xf6=\\xb1$O?HE?\\xbd\\xda\\xa9\\xbe=\\xf2\\xc4\\xf1\\xbei\\x8f\\xfb?\\x13}o?\\xf2&\\xc7\\xbf\\n\\xc9\\x9a<=\\x8c7@!\\xbf\\x80\\xbfk?\\xdb?9\\xb9\\x82?u\\x1a\\x16\\xbf\\xd5\\xee*\\xc0\\xc4\\x84\\x1a\\xbf\\xf8>q\\xbe\\x80\\xccu?\\xbe\\xeb\\xff\\xbeH\\x14\\xa1?\\xc4\\x80h>C\\\\\\x80\\xbe5\\x9f\\x12>A\\x16D\\xbf\\x007y>Q\\xaf\\x90@\\xe2\\xf6\\xed\\xbd; R?\\xda\\xe6\\xb9\\xbf\\xcbNZ\\xbf\\xd2\\xbe\\xe7?\\xf2E\\xe4\\xbfn\\xde\\x95\\xbf\\xdaq\\x84?B}\\x0b@}\\x90\\x9a?\\xbc\\x8f#?\\x94> \\xc0\\x82.\\xa0\\xbfaz\\x08?)\\x06L\\xbf\\xaa\\xe5\\xc9?9o\\x08@\\xd3\\x8e\\x0c\\xbe\\xbbb^?%\\x8f\\x0e\\xc0\\x90d-??X*?At*\\xbf\\xb8\\xb9\\x11\\xc0\\xf5\\x93\\xfb?RID\\xbf\\xcbZC@\\xfeu\\x18?rJ\\x81\\xbej\\xa4\\xce\\xbf]\\x99\\x7f<\\xd9\\x07\\x86>\\xd8z\\x9a?\\x13\\xa86\\xc0\\x18>\\xce?\\xac\\xa8+>Q\\xd9&@\\xfa\\xfc\\x85?\\nJ\\x8e\\xbfjx\\xc6?\\xbe\\x89`\\xc0\\xf2\\xad\\xd9?\\x967y?\\x8b\\xd2\\x98?\\xf5q\\x9e\\xbf\\x86|\\xa5?\\x9d\\xc5\\xc2\\xbe\\x9d\\xd2\\xc1\\xbf5:\\xca\\xbfp\\x8a\\x00>\\xb5Iy\\xc0\\x84\\x1b\\xa5\\xbf\\xf6\\xb7\\x84\\xbf\\xb0}\\x8e?+\\xea\\x0b@\\x10\\xc5\\xb9?_\\xadt\\xbfdw\\xaf\\xbe9=\\x19\\xbe\\xef\\x07\\x00<\\x12+X\\xbf\\xech\\xcb>e\\xa6\\x00#\\x9e\\x17\\xbfx\\x19\\x12\\xbf\\xaa8\\xb6\\xbf\\xcdLC\\xbf\\x8a\\x92\\xea\\xbd\\xa2\\x8ej\\xbf\\'\\xc7\\xff?&\\xad\\xfb\\xbd\\x9c\\x83 ?\\x12\\xa3U\\xbf\\x1a\\x83\\xf5>\\x8a\\xe5$\\xc0Z[\\x87\\xbf\\xbc\\x16\\xa3\\xbf\\xd7Z\\x81>\\r\\x0f\\x00\\xc0xx\\xb6\\xbfQ\\xdao\\xbf\\nV{?\\x01\\xb5\\x14@\\x93\\xc5z?F[\\x05\\xbfL\\x01\\t\\xc0\\xdd\\xee\\x02\\xc0\\x17j>@\\x87\\xde\\xfc?X\\xd2\\x04@\\x9d\\xfa\\x00\\xbd7\\xc0=\\xbf$\\x07)\\xbf\\xe1\\x13\\xa6>\\x9c\\xad\\x07\\xbf/Y.\\xbf/\\x99]\\xbfN\\xc6\\xa4?f\\xd1\\x91?\\xfaB\\xa7\\xbe\\x86\\xf06\\xbf\\xb1M\\x00\\xc0\\xf5\\xdb\\xdb\\xbf)\\xdc\\xfb?\\x9e\\xc8\\xe0?}gE@y\\xe1\\x81\\xc0\\xb7A\\xac\\xbe:\\xaf\\xcd>\\xabJ\\x82\\xbf\\xdb\\xbc\\x88?\\x1a\\xcd\\xa7>\\xf9\"\\r\\xbf\\x85l\\x82\\xbf\\x02T\\xce\\xbf~\\xe6\\x97\\xbe+c\\xa3?\\xd9\\xc6!@\\xc9zG@||L>\\x9e\\x0b\\xa4?t\\xa9\\xc6\\xbf\\xa9\\xdd\\xdd>\\r\\x00[\\xbf5\\xecH\\xbf)a\\xd8?\\xda\\xb4\\xe4\\xbf\\xec?\\xa3?Q5]?\\x8d\\xf3$@\\xfe\\xef\\x1e>\\xfc\\xf9\\x97?_`\\x02\\xbe\\xb4\\xf1.\\xbdv3R\\xbf$(4\\xc0wF\\xd5?\\x9a\\x19Y\\xbf\\xec\\x84\\xcb\\xbd\\xc0q\\x93?|1\\x16\\xbf\\x01\\x88G\\xbfZ\\x88\\x04>\\x9c\\xed\\x1a\\xbf%\\'\\x00?\\xb3\\xf5\\x18@\\'\\xb93\\xbfRw\\x95?]\\x82\\xb6?\\xf6h^\\xbf\\xf1\\x15\\x92?\\xb5\\xc1\\x01?\\xb3\\xf1\\x17\\xbf\\x19.|\\xbf\\xaa\\x05\\x9c\\xcb\\xce\\x08> g\\xcf\\xbe5\\xd0\\xa3\\xbf\\x8f*\\xc5\\xbeS\\x1d\\xc9>\\xfeG\\xcd\\xbf\\xf4\\xed\\x18@F|!@o\\x90!\\xbf\\xd4\\xf4+>\\xbc\\xb5\\x90?0\\xd94\\xbf\\x1e\\xa4\"\\xbe\\xca\\xb2.@\\xf2\\xbe\\xfa\\xbf\\xa0\\x90\\x8b\\xbf\\xc6\\xe8\\x16\\xbf|\\xa9.\\xbf\\x8f\\x94\\xd3\\xbf\\xfd\\n\\x08@\\x8f\\x18E?\\x14\\xab\\xaf?s\\xee\\xb2\\xbf\\xbb\\xfa\\x17\\xbe\\x84m\\x93?\\x06\\xf2]\\xbf\\xcdJ\\xc8\\xbe\\x88\\r\\xd4?\\xea\\xaa\\xe7>%\\x1a\\xca\\xbe\\xfb\\x01\\xab?Dx\\xfe>\\xabd\\x85= _4\\xbf\\xb2\\x99~?\\xf0H!?+\\xfaU?\\xa87\\xb1>M\\xe57\\xbfb\\xb6f?\\xb5,\\x00\\xc0\\xdb\\xbdA\\xc0C\\xb0\\xc2?\\xa3\\x00\\xc9\\xbe\\xb9\\xfdF\\xc0\\xb0\\n\\xcf?\\xe4\\x83\\x14\\xc00\\xc8\\xaf\\xbe\\xb7M@\\xbf3\\x17\\x98>Mw\\x19?_\\xc1[\\xbf6\\xa3\\x87\\xbe-\\xc0\\xb7\\xbf\\xae\\xd5:@\\xcd\\x13\\xac?\\xcd7\\xae\\xbe\\xbaT6@\\x8e/T?\\x89\\xe3U?>^\\xa1?\\x13b\\x95?+\\x0e\\x19\\xc0o\\xd6\"\\xbfO@\\x0c\\xc0\\xddJ\\xa5\\xbd\\x94`(\\xbc\\x87<*\\xbf7\\x1a\\x07?\\xe5Z\\x01\\xc0\\xce\\xb9P?]\\xea\\x00?D\\x89\\x8d?\\x02\\xbf\\xb8\\xbe\\x93\\xa1h\\xbfQ\\x1er?\\xa204\\xc02\\xc3\\xf1?\\xed \\x10@\\xae#\\xdf?\\xc5\\xc4\\xd7?\\x84\\xa7m\\xbf\\xbfv\\x96=\\x0c\\xc2z\\xbf\\xd1j\\x14@u\\x83\\x87=\\xd3\\x80K?\\x92:p\\xbfQ}\\x0b@\\xd5\\xd2\\x98\\xbf7w]>Vt\\x97\\xbe\\xa2\\xcc\\x11\\xbe\\xd8\\x9a\\x01\\xbf.\\x1f\\x13\\xc0\\xc5Q\\x18\\xc0-\"\\xfe\\xbf\\xa69V?\\xf5\\x08\\xc6\\xbf\\x1a5\\x0f\\xc0\\xbc50?\\rR\\xee?\\xb3\\x18q>i\\xf2U?*\\xfc\\xfc>*\\x1ez>\\xa1\\xee\\x1d\\xc0\\xd7\\x13\\x1e@r\\x9a\\x8e\\xbfy1r\\xbe\\x9e\\xda<@\\x06\\x82\\x89\\xbf\\x18\\xf8\\x10\\xc0}\\xd3\\xaa>\\x90\\xa4\\x07@U\\xcf\\x05?\\x14\\x93\\x05\\xc0\\xa4\\x12o@\\xf9\\xfd\\xea>A\\x14s?P\\xbe\\x93\\xbf\\xb6n\\x11\\xbfn\\xb9\\xc3\\xbd\\x1e\\x0c\\xa1=0\\xe7L\\xbe\\xca#%\\xc0\\x19\\xaa\\xc6>\\x13\\xbcR>\\xb5\\xa7T=|\\xcfh?#\\xa8\\xa5?\\x9e\\x8f\\x1d?\\xfc\\xc9\\x02@\\xe8\\x9e\\x99\\xbdA\\xc3O\\xbf\\xc5\\x06>>\"8\\x8e?\\x96\\xd2T\\xbf\\x91\\xf6\\x0e\\xc0f\\x95\\xc9\\xbf\\xdc\\x01\\x12@c\\n\\x01\\xc0\\x98\\xad?@\\xa0E\\xbc\\xbf\\x02\\x8b\\xd4\\xbf\\x83\\x97\\x86?\\x1d\\x16\\x05\\xc0\\xff>+\\xbf\\xb1\\xdb8>\\xbd\\xc2\\xf8?xe\\x9e?W\\x8c\\xec\\xbf\\xf5\\xc3\\x00@\\x96,\\x99=\\xd9\\xb0\\xd4\\xbe\\x93\\x94^?<\\xadA@%Ud\\xbe3\\xd9\\x15\\xc0b5\\x81?X\\xfe\\x18@\\xf5\\xe5\\xc0\\xbf\"\\x13\\x00@\\xd9\\xc61@\\xc7~\\xcd\\xbe\\x19o\\x8a\\xbf\\xb7\\xb9/\\xbfZdE\\xbf\\xd4\\xb8T\\xbfN\\x88\\x8d>\\tA.\\xbfd\\xac\\xba\\xc0m\\xbc_\\xbe\\x14\\xb7:\\xbe\\xcf \\xf5\\xbf\\xbb\\xfb\\xb6>\\xd5\\xc8\\x8c\\xbf\\xff\\xc6L@\\x91(\\xcd\\xbf\\x0e\\x83\\xc9>+-\\x9c?#{i\\xbf\\xe6\\x94\\xd6>\\xc4\\xd2i?XD\\xf2\\xbe\\xad\\x19p\\xbe\\x07\\xd9\\x99\\xbfO\\xe56\\xc0\\xb3]|>\\xd5\\x9df\\xbe\\xa5\\x9a\\x80>0\\x16\\xbf>\\xf8\\xeb\\xfb\\xbf\\x8ad\\xc8\\xbe:pt?m6\\xbe\\x1f\\x1f@', 'metadata': '{\"source\": \"geography\"}', 'entry_id': '115049a298532be2f181edb03f766770c0db84c22aff39003fec340deaec7545', 'response': 'Paris', 'inserted_at': '1772490439.163563', 'updated_at': '1772490439.163563'}\n" + ] + } + ], + "source": [ + "# Fetch a specific entry by its entry_id\n", + "entry_id = result[0]['entry_id']\n", + "record = llmcache._index.fetch(entry_id)\n", + "print(f\"Fetched record: {record}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": { + "execution": { + "iopub.execute_input": "2026-03-02T22:27:19.191818Z", + "iopub.status.busy": "2026-03-02T22:27:19.191742Z", + "iopub.status.idle": "2026-03-02T22:27:19.208758Z", + "shell.execute_reply": "2026-03-02T22:27:19.208251Z" + } + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "After deletion: []\n" + ] + } + ], + "source": [ + "# Delete specific entries by ID or key\n", + "# By entry IDs (without prefix):\n", + "llmcache.drop(ids=[entry_id])\n", + "\n", + "# Or by full Redis keys (with prefix):\n", + "# llmcache.drop(keys=[key])\n", + "\n", + "# Verify it's deleted\n", + "result = llmcache.check(prompt=\"What is the capital of France?\")\n", + "print(f\"After deletion: {result}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": { + "iopub.execute_input": "2026-02-16T15:30:34.501619Z", + "iopub.status.busy": "2026-02-16T15:30:34.501550Z", + "iopub.status.idle": "2026-02-16T15:30:40.622930Z", + "shell.execute_reply": "2026-02-16T15:30:40.621935Z" + } + }, "source": [ "## Customize the Distance Threshold\n", "\n", @@ -342,60 +542,64 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 15, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.339923Z", - "iopub.status.busy": "2026-02-16T15:30:34.339843Z", - "iopub.status.idle": "2026-02-16T15:30:34.341651Z", - "shell.execute_reply": "2026-02-16T15:30:34.341233Z" + "iopub.execute_input": "2026-03-02T22:27:19.209760Z", + "iopub.status.busy": "2026-03-02T22:27:19.209694Z", + "iopub.status.idle": "2026-03-02T22:27:19.211140Z", + "shell.execute_reply": "2026-03-02T22:27:19.210821Z" } }, "outputs": [], "source": [ "# Widen the semantic distance threshold (allow less similar matches)\n", - "llmcache.set_threshold(0.5)" + "llmcache.set_threshold(0.5)\n", + "\n", + "# Re-store an entry for the threshold demo\n", + "llmcache.store(prompt=\"What is the capital of France?\", response=\"Paris\")" ] }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 16, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.342644Z", - "iopub.status.busy": "2026-02-16T15:30:34.342568Z", - "iopub.status.idle": "2026-02-16T15:30:34.450098Z", - "shell.execute_reply": "2026-02-16T15:30:34.449695Z" + "iopub.execute_input": "2026-03-02T22:27:19.212053Z", + "iopub.status.busy": "2026-03-02T22:27:19.211987Z", + "iopub.status.idle": "2026-03-02T22:27:19.335363Z", + "shell.execute_reply": "2026-03-02T22:27:19.335034Z" } }, "outputs": [ { - "data": { - "text/plain": [ - "'Paris'" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" + "ename": "IndexError", + "evalue": "list index out of range", + "output_type": "error", + "traceback": [ + "\u001b[31m---------------------------------------------------------------------------\u001b[39m", + "\u001b[31mIndexError\u001b[39m Traceback (most recent call last)", + "\u001b[36mCell\u001b[39m\u001b[36m \u001b[39m\u001b[32mIn[16]\u001b[39m\u001b[32m, line 4\u001b[39m\n\u001b[32m 1\u001b[39m \u001b[38;5;66;03m# Really try to trick it by asking around the point\u001b[39;00m\n\u001b[32m 2\u001b[39m \u001b[38;5;66;03m# But is able to slip just under our new threshold\u001b[39;00m\n\u001b[32m 3\u001b[39m question = \u001b[33m\"\u001b[39m\u001b[33mWhat is the capital city of the country in Europe that also has a city named Nice?\u001b[39m\u001b[33m\"\u001b[39m\n\u001b[32m----> \u001b[39m\u001b[32m4\u001b[39m \u001b[43mllmcache\u001b[49m\u001b[43m.\u001b[49m\u001b[43mcheck\u001b[49m\u001b[43m(\u001b[49m\u001b[43mprompt\u001b[49m\u001b[43m=\u001b[49m\u001b[43mquestion\u001b[49m\u001b[43m)\u001b[49m\u001b[43m[\u001b[49m\u001b[32;43m0\u001b[39;49m\u001b[43m]\u001b[49m[\u001b[33m'\u001b[39m\u001b[33mresponse\u001b[39m\u001b[33m'\u001b[39m]\n", + "\u001b[31mIndexError\u001b[39m: list index out of range" + ] } ], "source": [ "# Really try to trick it by asking around the point\n", "# But is able to slip just under our new threshold\n", - "question = \"What is the capital city of the country in Europe that also has a city named Nice?\"\n", + "question = \"What is the capital of the country where Nice is located?\"\n", "llmcache.check(prompt=question)[0]['response']" ] }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 17, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.451349Z", - "iopub.status.busy": "2026-02-16T15:30:34.451264Z", - "iopub.status.idle": "2026-02-16T15:30:34.497746Z", - "shell.execute_reply": "2026-02-16T15:30:34.497352Z" + "iopub.execute_input": "2026-03-02T22:27:19.336679Z", + "iopub.status.busy": "2026-03-02T22:27:19.336607Z", + "iopub.status.idle": "2026-03-02T22:27:19.528757Z", + "shell.execute_reply": "2026-03-02T22:27:19.528421Z" } }, "outputs": [ @@ -405,7 +609,7 @@ "[]" ] }, - "execution_count": 12, + "execution_count": 17, "metadata": {}, "output_type": "execute_result" } @@ -420,7 +624,14 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "execution": { + "iopub.execute_input": "2026-02-16T15:30:40.690563Z", + "iopub.status.busy": "2026-02-16T15:30:40.690480Z", + "iopub.status.idle": "2026-02-16T15:30:40.692398Z", + "shell.execute_reply": "2026-02-16T15:30:40.692093Z" + } + }, "source": [ "## Utilize TTL\n", "\n", @@ -432,13 +643,13 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 18, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.498916Z", - "iopub.status.busy": "2026-02-16T15:30:34.498837Z", - "iopub.status.idle": "2026-02-16T15:30:34.500656Z", - "shell.execute_reply": "2026-02-16T15:30:34.500207Z" + "iopub.execute_input": "2026-03-02T22:27:19.530027Z", + "iopub.status.busy": "2026-03-02T22:27:19.529953Z", + "iopub.status.idle": "2026-03-02T22:27:19.531640Z", + "shell.execute_reply": "2026-03-02T22:27:19.531259Z" } }, "outputs": [], @@ -448,13 +659,13 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 19, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:34.501619Z", - "iopub.status.busy": "2026-02-16T15:30:34.501550Z", - "iopub.status.idle": "2026-02-16T15:30:40.622930Z", - "shell.execute_reply": "2026-02-16T15:30:40.621935Z" + "iopub.execute_input": "2026-03-02T22:27:19.532553Z", + "iopub.status.busy": "2026-03-02T22:27:19.532488Z", + "iopub.status.idle": "2026-03-02T22:27:25.571873Z", + "shell.execute_reply": "2026-03-02T22:27:25.570669Z" } }, "outputs": [], @@ -466,13 +677,13 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 20, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:40.624998Z", - "iopub.status.busy": "2026-02-16T15:30:40.624839Z", - "iopub.status.idle": "2026-02-16T15:30:40.686437Z", - "shell.execute_reply": "2026-02-16T15:30:40.685943Z" + "iopub.execute_input": "2026-03-02T22:27:25.574715Z", + "iopub.status.busy": "2026-03-02T22:27:25.574488Z", + "iopub.status.idle": "2026-03-02T22:27:25.626243Z", + "shell.execute_reply": "2026-03-02T22:27:25.625703Z" } }, "outputs": [ @@ -493,13 +704,13 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 21, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:40.687665Z", - "iopub.status.busy": "2026-02-16T15:30:40.687576Z", - "iopub.status.idle": "2026-02-16T15:30:40.689464Z", - "shell.execute_reply": "2026-02-16T15:30:40.688989Z" + "iopub.execute_input": "2026-03-02T22:27:25.627948Z", + "iopub.status.busy": "2026-03-02T22:27:25.627806Z", + "iopub.status.idle": "2026-03-02T22:27:25.629706Z", + "shell.execute_reply": "2026-03-02T22:27:25.629282Z" } }, "outputs": [], @@ -511,6 +722,74 @@ { "cell_type": "markdown", "metadata": {}, + "source": [ + "### TTL Behavior Details\n", + "\n", + "Understanding how TTL works with `SemanticCache` is important for production use:\n", + "\n", + "| Scenario | Behavior |\n", + "|----------|----------|\n", + "| `ttl=None` (default) | Entries persist forever. `check()` does not affect TTL. |\n", + "| `ttl=3600` at init | Entries get TTL on `store()`. TTL is **refreshed** on every `check()` hit. |\n", + "| Set TTL later with `set_ttl(3600)` | **Existing entries keep no TTL**, but `check()` will now **add** TTL to matched entries. |\n", + "| Remove TTL with `set_ttl(None)` | Existing entries keep their TTL, but `check()` no longer refreshes it. |\n", + "\n", + "**Important:** The `check()` method automatically refreshes TTL on all matched entries (sliding window pattern). This keeps frequently accessed entries alive but can unexpectedly add TTL to entries that were originally stored without one." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": { + "iopub.execute_input": "2026-02-16T15:30:48.730938Z", + "iopub.status.busy": "2026-02-16T15:30:48.730860Z", + "iopub.status.idle": "2026-02-16T15:31:03.090895Z", + "shell.execute_reply": "2026-02-16T15:31:03.090496Z" + } + }, + "source": [ + "### TTL Refresh on Check\n", + "\n", + "When `check()` finds matching entries, it refreshes the TTL on **all** matched results, not just the one you use:" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": { + "execution": { + "iopub.execute_input": "2026-03-02T22:27:25.631158Z", + "iopub.status.busy": "2026-03-02T22:27:25.631047Z", + "iopub.status.idle": "2026-03-02T22:27:25.848115Z", + "shell.execute_reply": "2026-03-02T22:27:25.847562Z" + } + }, + "outputs": [], + "source": [ + "# Example: TTL refresh behavior\n", + "llmcache.set_ttl(300) # 5 minutes\n", + "\n", + "# Store an entry\n", + "llmcache.store(\"What is Python?\", \"A programming language\")\n", + "\n", + "# Every time check() finds this entry, TTL resets to 300 seconds\n", + "result = llmcache.check(\"What is Python?\") # TTL refreshed\n", + "\n", + "# Reset for next examples\n", + "llmcache.set_ttl()\n", + "llmcache.clear()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "execution": { + "iopub.execute_input": "2026-02-16T15:31:03.134804Z", + "iopub.status.busy": "2026-02-16T15:31:03.134726Z", + "iopub.status.idle": "2026-02-16T15:31:03.137313Z", + "shell.execute_reply": "2026-02-16T15:31:03.136962Z" + } + }, "source": [ "## Simple Performance Testing\n", "\n", @@ -519,13 +798,13 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 23, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:40.690563Z", - "iopub.status.busy": "2026-02-16T15:30:40.690480Z", - "iopub.status.idle": "2026-02-16T15:30:40.692398Z", - "shell.execute_reply": "2026-02-16T15:30:40.692093Z" + "iopub.execute_input": "2026-03-02T22:27:25.849247Z", + "iopub.status.busy": "2026-03-02T22:27:25.849178Z", + "iopub.status.idle": "2026-03-02T22:27:25.851000Z", + "shell.execute_reply": "2026-03-02T22:27:25.850678Z" } }, "outputs": [], @@ -550,13 +829,13 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 24, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:40.693572Z", - "iopub.status.busy": "2026-02-16T15:30:40.693493Z", - "iopub.status.idle": "2026-02-16T15:30:45.605328Z", - "shell.execute_reply": "2026-02-16T15:30:45.604820Z" + "iopub.execute_input": "2026-03-02T22:27:25.852175Z", + "iopub.status.busy": "2026-03-02T22:27:25.852108Z", + "iopub.status.idle": "2026-03-02T22:27:26.747258Z", + "shell.execute_reply": "2026-03-02T22:27:26.746631Z" } }, "outputs": [ @@ -564,7 +843,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "Without caching, a call to openAI to answer this simple question took 3.055630922317505 seconds.\n" + "Without caching, a call to openAI to answer this simple question took 0.865767240524292 seconds.\n" ] }, { @@ -573,7 +852,7 @@ "'llmcache:67e0f6e28fe2a61c0022fd42bf734bb8ffe49d3e375fd69d692574295a20fc1a'" ] }, - "execution_count": 18, + "execution_count": 24, "metadata": {}, "output_type": "execute_result" } @@ -593,13 +872,13 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 25, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:45.606711Z", - "iopub.status.busy": "2026-02-16T15:30:45.606608Z", - "iopub.status.idle": "2026-02-16T15:30:46.019546Z", - "shell.execute_reply": "2026-02-16T15:30:46.019062Z" + "iopub.execute_input": "2026-03-02T22:27:26.748828Z", + "iopub.status.busy": "2026-03-02T22:27:26.748703Z", + "iopub.status.idle": "2026-03-02T22:27:26.882071Z", + "shell.execute_reply": "2026-03-02T22:27:26.881633Z" } }, "outputs": [ @@ -607,8 +886,8 @@ "name": "stdout", "output_type": "stream", "text": [ - "Avg time taken with LLM cache enabled: 0.05140402317047119\n", - "Percentage of time saved: 98.32%\n" + "Avg time taken with LLM cache enabled: 0.013062572479248047\n", + "Percentage of time saved: 98.49%\n" ] } ], @@ -629,13 +908,13 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 26, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:46.020637Z", - "iopub.status.busy": "2026-02-16T15:30:46.020555Z", - "iopub.status.idle": "2026-02-16T15:30:48.724038Z", - "shell.execute_reply": "2026-02-16T15:30:48.723375Z" + "iopub.execute_input": "2026-03-02T22:27:26.883298Z", + "iopub.status.busy": "2026-03-02T22:27:26.883214Z", + "iopub.status.idle": "2026-03-02T22:27:27.253878Z", + "shell.execute_reply": "2026-03-02T22:27:27.253166Z" } }, "outputs": [ @@ -643,31 +922,31 @@ "name": "stdout", "output_type": "stream", "text": [ - "\n", - "Statistics:\n", - "╭─────────────────────────────┬────────────╮\n", - "│ Stat Key │ Value │\n", - "├─────────────────────────────┼────────────┤\n", - "│ num_docs │ 1 │\n", - "│ num_terms │ 19 │\n", - "│ max_doc_id │ 4 │\n", - "│ num_records │ 36 │\n", - "│ percent_indexed │ 1 │\n", - "│ hash_indexing_failures │ 0 │\n", - "│ number_of_uses │ 19 │\n", - "│ bytes_per_record_avg │ 62.3888893 │\n", - "│ doc_table_size_mb │ 0.00782489 │\n", - "│ inverted_sz_mb │ 0.00214195 │\n", - "│ key_table_size_mb │ 1.14440917 │\n", - "│ offset_bits_per_record_avg │ 8 │\n", - "│ offset_vectors_sz_mb │ 2.67028808 │\n", - "│ offsets_per_term_avg │ 0.77777779 │\n", - "│ records_per_doc_avg │ 36 │\n", - "│ sortable_values_size_mb │ 0 │\n", - "│ total_indexing_time │ 1.366666 │\n", - "│ total_inverted_index_blocks │ 21 │\n", - "│ vector_index_sz_mb │ 3.01630401 │\n", - "╰─────────────────────────────┴────────────╯\n" + "\r\n", + "Statistics:\r\n", + "\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\r\n", + "\u2502 Stat Key \u2502 Value \u2502\r\n", + "\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\r\n", + "\u2502 num_docs \u2502 1 \u2502\r\n", + "\u2502 num_terms \u2502 24 \u2502\r\n", + "\u2502 max_doc_id \u2502 9 \u2502\r\n", + "\u2502 num_records \u2502 88 \u2502\r\n", + "\u2502 percent_indexed \u2502 1 \u2502\r\n", + "\u2502 hash_indexing_failures \u2502 0 \u2502\r\n", + "\u2502 number_of_uses \u2502 41 \u2502\r\n", + "\u2502 bytes_per_record_avg \u2502 34.8636360 \u2502\r\n", + "\u2502 doc_table_size_mb \u2502 0.01545429 \u2502\r\n", + "\u2502 inverted_sz_mb \u2502 0.00292587 \u2502\r\n", + "\u2502 key_table_size_mb \u2502 2.76565551 \u2502\r\n", + "\u2502 offset_bits_per_record_avg \u2502 8 \u2502\r\n", + "\u2502 offset_vectors_sz_mb \u2502 6.00814819 \u2502\r\n", + "\u2502 offsets_per_term_avg \u2502 0.71590906 \u2502\r\n", + "\u2502 records_per_doc_avg \u2502 88 \u2502\r\n", + "\u2502 sortable_values_size_mb \u2502 0 \u2502\r\n", + "\u2502 total_indexing_time \u2502 1.14699995 \u2502\r\n", + "\u2502 total_inverted_index_blocks \u2502 103 \u2502\r\n", + "\u2502 vector_index_sz_mb \u2502 3.01609802 \u2502\r\n", + "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\r\n" ] } ], @@ -678,13 +957,13 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 27, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:48.725899Z", - "iopub.status.busy": "2026-02-16T15:30:48.725759Z", - "iopub.status.idle": "2026-02-16T15:30:48.729675Z", - "shell.execute_reply": "2026-02-16T15:30:48.729206Z" + "iopub.execute_input": "2026-03-02T22:27:27.256087Z", + "iopub.status.busy": "2026-03-02T22:27:27.255947Z", + "iopub.status.idle": "2026-03-02T22:27:27.259425Z", + "shell.execute_reply": "2026-03-02T22:27:27.258824Z" } }, "outputs": [], @@ -695,7 +974,14 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "execution": { + "iopub.execute_input": "2026-02-16T15:31:17.839962Z", + "iopub.status.busy": "2026-02-16T15:31:17.839884Z", + "iopub.status.idle": "2026-02-16T15:31:17.842367Z", + "shell.execute_reply": "2026-02-16T15:31:17.841965Z" + } + }, "source": [ "## Cache Access Controls, Tags & Filters\n", "When running complex workflows with similar applications, or handling multiple users it's important to keep data segregated. Building on top of RedisVL's support for complex and hybrid queries we can tag and filter cache entries using custom-defined `filterable_fields`.\n", @@ -705,16 +991,27 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 28, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:30:48.730938Z", - "iopub.status.busy": "2026-02-16T15:30:48.730860Z", - "iopub.status.idle": "2026-02-16T15:31:03.090895Z", - "shell.execute_reply": "2026-02-16T15:31:03.090496Z" + "iopub.execute_input": "2026-03-02T22:27:27.260983Z", + "iopub.status.busy": "2026-03-02T22:27:27.260860Z", + "iopub.status.idle": "2026-03-02T22:27:28.685952Z", + "shell.execute_reply": "2026-03-02T22:27:28.685577Z" } }, - "outputs": [], + "outputs": [ + { + "data": { + "text/plain": [ + "'private_cache:2831a0659fb888e203cd9fedb9f65681bfa55e4977c092ed1bf87d42d2655081'" + ] + }, + "execution_count": 28, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ "private_cache = SemanticCache(\n", " name=\"private_cache\",\n", @@ -736,13 +1033,13 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 29, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:31:03.092088Z", - "iopub.status.busy": "2026-02-16T15:31:03.092010Z", - "iopub.status.idle": "2026-02-16T15:31:03.133762Z", - "shell.execute_reply": "2026-02-16T15:31:03.133324Z" + "iopub.execute_input": "2026-03-02T22:27:28.687207Z", + "iopub.status.busy": "2026-03-02T22:27:28.687128Z", + "iopub.status.idle": "2026-03-02T22:27:28.702859Z", + "shell.execute_reply": "2026-03-02T22:27:28.702301Z" } }, "outputs": [ @@ -772,13 +1069,13 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": 30, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:31:03.134804Z", - "iopub.status.busy": "2026-02-16T15:31:03.134726Z", - "iopub.status.idle": "2026-02-16T15:31:03.137313Z", - "shell.execute_reply": "2026-02-16T15:31:03.136962Z" + "iopub.execute_input": "2026-03-02T22:27:28.703922Z", + "iopub.status.busy": "2026-03-02T22:27:28.703855Z", + "iopub.status.idle": "2026-03-02T22:27:28.706653Z", + "shell.execute_reply": "2026-03-02T22:27:28.706152Z" } }, "outputs": [], @@ -796,16 +1093,27 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 31, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:31:03.138485Z", - "iopub.status.busy": "2026-02-16T15:31:03.138420Z", - "iopub.status.idle": "2026-02-16T15:31:17.795752Z", - "shell.execute_reply": "2026-02-16T15:31:17.795268Z" + "iopub.execute_input": "2026-03-02T22:27:28.707741Z", + "iopub.status.busy": "2026-03-02T22:27:28.707677Z", + "iopub.status.idle": "2026-03-02T22:27:30.110548Z", + "shell.execute_reply": "2026-03-02T22:27:30.110170Z" } }, - "outputs": [], + "outputs": [ + { + "data": { + "text/plain": [ + "'account_data:944f89729b09ca46b99923d223db45e0bccf584cfd53fcaf87d2a58f072582d3'" + ] + }, + "execution_count": 31, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ "\n", "complex_cache = SemanticCache(\n", @@ -841,13 +1149,13 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": 32, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:31:17.796921Z", - "iopub.status.busy": "2026-02-16T15:31:17.796847Z", - "iopub.status.idle": "2026-02-16T15:31:17.838671Z", - "shell.execute_reply": "2026-02-16T15:31:17.838340Z" + "iopub.execute_input": "2026-03-02T22:27:30.111876Z", + "iopub.status.busy": "2026-03-02T22:27:30.111792Z", + "iopub.status.idle": "2026-03-02T22:27:30.126746Z", + "shell.execute_reply": "2026-03-02T22:27:30.126340Z" } }, "outputs": [ @@ -900,13 +1208,13 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": 33, "metadata": { "execution": { - "iopub.execute_input": "2026-02-16T15:31:17.839962Z", - "iopub.status.busy": "2026-02-16T15:31:17.839884Z", - "iopub.status.idle": "2026-02-16T15:31:17.842367Z", - "shell.execute_reply": "2026-02-16T15:31:17.841965Z" + "iopub.execute_input": "2026-03-02T22:27:30.128133Z", + "iopub.status.busy": "2026-03-02T22:27:30.128057Z", + "iopub.status.idle": "2026-03-02T22:27:30.130139Z", + "shell.execute_reply": "2026-03-02T22:27:30.129753Z" } }, "outputs": [], @@ -931,9 +1239,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.13.2" + "version": "3.12.6" } }, "nbformat": 4, "nbformat_minor": 2 -} +} \ No newline at end of file diff --git a/redisvl/__init__.py b/redisvl/__init__.py index ebc97c27..40a306eb 100644 --- a/redisvl/__init__.py +++ b/redisvl/__init__.py @@ -1,3 +1,3 @@ from redisvl.version import __version__ -all = ["__version__"] +__all__ = ["__version__"] diff --git a/redisvl/query/__init__.py b/redisvl/query/__init__.py index 3f78c755..047aec9f 100644 --- a/redisvl/query/__init__.py +++ b/redisvl/query/__init__.py @@ -26,6 +26,7 @@ "VectorRangeQuery", "CountQuery", "TextQuery", + "HybridQuery", "AggregationQuery", "AggregateHybridQuery", "MultiVectorQuery", diff --git a/redisvl/query/query.py b/redisvl/query/query.py index e96ffd78..44e714b3 100644 --- a/redisvl/query/query.py +++ b/redisvl/query/query.py @@ -1332,7 +1332,7 @@ class TextQuery(BaseQuery): from redisvl.query import TextQuery from redisvl.index import SearchIndex - index = SearchIndex.from_yaml(index.yaml) + index = SearchIndex.from_yaml("index.yaml") query = TextQuery( text="example text", diff --git a/redisvl/schema/schema.py b/redisvl/schema/schema.py index 7d89cf89..66384cc5 100644 --- a/redisvl/schema/schema.py +++ b/redisvl/schema/schema.py @@ -343,7 +343,7 @@ def add_field(self, field_inputs: Dict[str, Any]): .. code-block:: python # Add a tag field - schema.add_field({"name": "user", "type": "tag}) + schema.add_field({"name": "user", "type": "tag"}) # Add a vector field schema.add_field({