graphrag-cache 3.0.1__tar.gz → 3.0.3__tar.gz

{graphrag_cache-3.0.1 → graphrag_cache-3.0.3}/.gitignore

@@ -63,3 +63,7 @@ docsite/
 
 # Root build assets
 packages/*/LICENSE
+
+# Notebooks outputs
+packages/graphrag-*/example_notebooks/**/output
+packages/graphrag-*/example_notebooks/**/cache

{graphrag_cache-3.0.1 → graphrag_cache-3.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrag-cache
-Version: 3.0.1
+Version: 3.0.3
 Summary: GraphRAG cache package.
 Project-URL: Source, https://github.com/microsoft/graphrag
 Author: Mónica Carvajal
@@ -12,8 +12,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.11
-Requires-Dist: graphrag-common==3.0.1
-Requires-Dist: graphrag-storage==3.0.1
+Requires-Dist: graphrag-common==3.0.2
+Requires-Dist: graphrag-storage==3.0.2
 Description-Content-Type: text/markdown
 
 # GraphRAG Cache
@@ -24,80 +24,13 @@ This package contains a collection of utilities to handle GraphRAG caching imple
 
 This example shows how to create a JSON cache with file storage using the GraphRAG cache package's configuration system. 
 
-```python
-import asyncio
-from graphrag_storage import StorageConfig, create_storage, StorageType
-from graphrag_cache import CacheConfig, create_cache, CacheType, create_cache_key
-
-async def run():
-    cache = create_cache()
-
-    # The above is equivalent to the following:
-    cache = create_cache(
-        CacheConfig(
-            type=CacheType.Json,
-            storage=StorageConfig(
-                type=StorageType.File,
-                base_dir="cache"
-            )
-        ),
-    )
-
-    await cache.set("my_key", {"some": "object to cache"})
-    print(await cache.get("my_key"))
-
-    # create cache key from data dict.
-    cache_key = create_cache_key({
-        "some_arg": "some_value",
-        "something_else": 5
-    })
-    await cache.set(cache_key, {"some": "object to cache"})
-    print(await cache.get(cache_key))
-
-if __name__ == "__main__":
-    asyncio.run(run())
-```
+[Open the notebook to explore the basic example code](example-notebooks/basic_cache_example.ipynb)
 
 ### Custom Cache
 
-This demonstrates how to create a custom cache implementation by extending the base Cache class and registering it with the GraphRAG cache system. Once registered, the custom cache can be instantiated through the factory pattern using either CacheConfig or directly via cache_factory, allowing for extensible caching solutions tailored to specific needs.
+This example demonstrates how to create a custom cache implementation by extending the base Cache class and registering it with the GraphRAG cache system. Once registered, the custom cache can be instantiated through the factory pattern using either CacheConfig or directly via cache_factory, allowing for extensible caching solutions tailored to specific needs.
 
-```python
-import asyncio
-from typing import Any
-from graphrag_storage import Storage
-from graphrag_cache import Cache, CacheConfig, create_cache, register_cache
-
-class MyCache(Cache):
-    def __init__(self, some_setting: str, optional_setting: str = "default setting", **kwargs: Any):
-        # Validate settings and initialize
-        # View the JsonCache implementation to see how to create a cache that relies on a Storage provider.
-        ...
-
-    #Implement rest of interface
-    ...
-
-register_cache("MyCache", MyCache)
-
-async def run():
-    cache = create_cache(
-        CacheConfig(
-            type="MyCache",
-            some_setting="My Setting"
-        )
-    )
-
-    # Or use the factory directly to instantiate with a dict instead of using
-    # CacheConfig + create_factory
-    # from graphrag_cache.cache_factory import cache_factory
-    # cache = cache_factory.create(strategy="MyCache", init_args={"some_setting": "My Setting"})
-
-    await cache.set("my_key", {"some": "object to cache"})
-    print(await cache.get("my_key"))
-
-if __name__ == "__main__":
-    asyncio.run(run())
-```
+[Open the notebook to explore the basic custom example code](example-notebooks/custom_cache_example.ipynb)
 
 #### Details
 

graphrag_cache-3.0.3/README.md

@@ -0,0 +1,42 @@
+# GraphRAG Cache
+
+This package contains a collection of utilities to handle GraphRAG caching implementation.
+
+### Basic
+
+This example shows how to create a JSON cache with file storage using the GraphRAG cache package's configuration system. 
+
+[Open the notebook to explore the basic example code](example-notebooks/basic_cache_example.ipynb)
+
+### Custom Cache
+
+This example demonstrates how to create a custom cache implementation by extending the base Cache class and registering it with the GraphRAG cache system. Once registered, the custom cache can be instantiated through the factory pattern using either CacheConfig or directly via cache_factory, allowing for extensible caching solutions tailored to specific needs.
+
+[Open the notebook to explore the basic custom example code](example-notebooks/custom_cache_example.ipynb)
+
+#### Details
+
+By default, the `create_cache` comes with the following cache providers registered that correspond to the entries in the `CacheType` enum. 
+
+- `JsonCache`
+- `MemoryCache`
+- `NoopCache`
+
+The preregistration happens dynamically, e.g., `JsonCache` is only imported and registered if you request a `JsonCache` with `create_cache(CacheType.Json, ...)`. There is no need to manually import and register builtin cache providers when using `create_cache`.
+
+If you want a clean factory with no preregistered cache providers then directly import `cache_factory` and bypass using `create_cache`. The downside is that `cache_factory.create` uses a dict for init args instead of the strongly typed `CacheConfig` used with `create_cache`.
+
+```python
+from graphrag_cache.cache_factory import cache_factory
+from graphrag_cache.json_cache import JsonCache
+
+# cache_factory has no preregistered providers so you must register any
+# providers you plan on using.
+# May also register a custom implementation, see above for example.
+cache_factory.register("my_cache_impl", JsonCache)
+
+cache = cache_factory.create(strategy="my_cache_impl", init_args={"some_setting": "..."})
+
+...
+
+```

graphrag_cache-3.0.3/example_notebooks/basic_cache_example.ipynb

@@ -0,0 +1,96 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "fcb917cf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Copyright (c) 2026 Microsoft Corporation.\n",
+    "# Licensed under the MIT License."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "33461307",
+   "metadata": {},
+   "source": [
+    "## Basic cache example\n",
+    "\n",
+    "This example shows how to create a JSON cache with file storage using the GraphRAG cache package's configuration system. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "ee33abd6",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Value stored in cache for 'my_key':\n",
+      "{'k1': 'object to cache'}\n",
+      "\n",
+      "Value stored in cache for cache_key using data dict:\n",
+      "{'k2': 'object to cache'}\n"
+     ]
+    }
+   ],
+   "source": [
+    "from graphrag_cache import CacheConfig, CacheType, create_cache, create_cache_key\n",
+    "from graphrag_storage import StorageConfig, StorageType\n",
+    "\n",
+    "\n",
+    "async def run():\n",
+    "    \"\"\"Demonstrate basic cache usage with graphrag_cache.\"\"\"\n",
+    "    cache = create_cache()\n",
+    "\n",
+    "    # The above is equivalent to the following:\n",
+    "    cache = create_cache(\n",
+    "        CacheConfig(\n",
+    "            type=CacheType.Json,\n",
+    "            storage=StorageConfig(type=StorageType.File, base_dir=\"cache\"),\n",
+    "        ),\n",
+    "    )\n",
+    "\n",
+    "    await cache.set(\"my_key\", {\"k1\": \"object to cache\"})\n",
+    "    print(\"Value stored in cache for 'my_key':\")\n",
+    "    print(await cache.get(\"my_key\"))\n",
+    "\n",
+    "    # create cache key from data dict.\n",
+    "    cache_key = create_cache_key({\"some_arg\": \"some_value\", \"something_else\": 5})\n",
+    "    await cache.set(cache_key, {\"k2\": \"object to cache\"})\n",
+    "    print(\"\\nValue stored in cache for cache_key using data dict:\")\n",
+    "    print(await cache.get(cache_key))\n",
+    "\n",
+    "\n",
+    "if __name__ == \"__main__\":\n",
+    "    await run()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

graphrag_cache-3.0.3/example_notebooks/cache/b458747d203b17cc97749f20a73cb58667baa348777917ef1e2a9384d145e5f0

@@ -0,0 +1 @@
+{"result": {"k2": "object to cache"}}

graphrag_cache-3.0.3/example_notebooks/cache/my_key

@@ -0,0 +1 @@
+{"result": {"k1": "object to cache"}}

graphrag_cache-3.0.3/example_notebooks/custom_cache_example.ipynb

@@ -0,0 +1,129 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "42524e97",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Copyright (c) 2026 Microsoft Corporation.\n",
+    "# Licensed under the MIT License."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a7cd6743",
+   "metadata": {},
+   "source": [
+    "## Custom cache example\n",
+    "\n",
+    "This example demonstrates how to create a custom cache implementation by extending the base Cache class and registering it with the GraphRAG cache system. Once registered, the custom cache can be instantiated through the factory pattern using either CacheConfig or directly via cache_factory, allowing for extensible caching solutions tailored to specific needs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "e7ec8dc1",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Value stored in cache for 'my_key':\n",
+      "{'k1': 'object to cache'}\n"
+     ]
+    }
+   ],
+   "source": [
+    "from typing import Any\n",
+    "\n",
+    "from graphrag_cache import Cache, CacheConfig, create_cache, register_cache\n",
+    "\n",
+    "\n",
+    "class MyCache(Cache):\n",
+    "    \"\"\"Custom cache implementation for storing and retrieving cached data.\"\"\"\n",
+    "\n",
+    "    def __init__(\n",
+    "        self,\n",
+    "        some_setting: str,\n",
+    "        optional_setting: str = \"default setting\",\n",
+    "        **kwargs: Any,\n",
+    "    ):\n",
+    "        # Validate settings and initialize\n",
+    "        # View the JsonCache implementation to see how to create a cache that relies on a Storage provider.\n",
+    "        self.some_setting = some_setting\n",
+    "        self.optional_setting = optional_setting\n",
+    "        self._cache: dict[str, Any] = {}\n",
+    "        self._child: Cache = self\n",
+    "\n",
+    "    async def get(self, key: str) -> Any:\n",
+    "        \"\"\"Retrieve a value from the cache by key.\"\"\"\n",
+    "        return self._cache.get(key)\n",
+    "\n",
+    "    async def set(self, key: str, value: Any, debug_data: Any = None) -> None:\n",
+    "        \"\"\"Store a value in the cache with the specified key.\"\"\"\n",
+    "        self._cache[key] = value\n",
+    "\n",
+    "    async def has(self, key: str) -> bool:\n",
+    "        \"\"\"Check if a key exists in the cache.\"\"\"\n",
+    "        return key in self._cache\n",
+    "\n",
+    "    async def delete(self, key: str) -> None:\n",
+    "        \"\"\"Remove a key and its value from the cache.\"\"\"\n",
+    "        self._cache.pop(key, None)\n",
+    "\n",
+    "    async def clear(self) -> None:\n",
+    "        \"\"\"Clear all items from the cache.\"\"\"\n",
+    "        self._cache.clear()\n",
+    "\n",
+    "    def child(self, name: str) -> Cache:\n",
+    "        \"\"\"Create or access a child cache (not implemented in this example).\"\"\"\n",
+    "        return self._child\n",
+    "\n",
+    "\n",
+    "register_cache(\"MyCache\", MyCache)\n",
+    "\n",
+    "\n",
+    "async def run():\n",
+    "    \"\"\"Demonstrate usage of the custom cache implementation.\"\"\"\n",
+    "    cache = create_cache(\n",
+    "        CacheConfig(\n",
+    "            type=\"MyCache\",\n",
+    "            some_setting=\"important setting value\",  # type: ignore\n",
+    "        )\n",
+    "    )\n",
+    "\n",
+    "    await cache.set(\"my_key\", {\"k1\": \"object to cache\"})\n",
+    "    print(\"Value stored in cache for 'my_key':\")\n",
+    "    print(await cache.get(\"my_key\"))\n",
+    "\n",
+    "\n",
+    "if __name__ == \"__main__\":\n",
+    "    await run()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{graphrag_cache-3.0.1 → graphrag_cache-3.0.3}/graphrag_cache/cache_factory.py

@@ -5,20 +5,14 @@
 """Cache factory implementation."""
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING
 
-from graphrag_common.factory import Factory
-from graphrag_storage import create_storage
+from graphrag_common.factory import Factory, ServiceScope
+from graphrag_storage import Storage, create_storage
 
+from graphrag_cache.cache import Cache
 from graphrag_cache.cache_config import CacheConfig
 from graphrag_cache.cache_type import CacheType
 
-if TYPE_CHECKING:
-    from graphrag_common.factory import ServiceScope
-    from graphrag_storage import Storage
-
-    from graphrag_cache.cache import Cache
-
 
 class CacheFactory(Factory["Cache"]):
     """A factory class for cache implementations."""
@@ -29,8 +23,8 @@ cache_factory = CacheFactory()
 
 def register_cache(
     cache_type: str,
-    cache_initializer: Callable[..., "Cache"],
-    scope: "ServiceScope" = "transient",
+    cache_initializer: Callable[..., Cache],
+    scope: ServiceScope = "transient",
 ) -> None:
     """Register a custom cache implementation.
 
@@ -45,7 +39,7 @@ def register_cache(
 
 
 def create_cache(
-    config: CacheConfig | None = None, storage: "Storage | None" = None
+    config: CacheConfig | None = None, storage: Storage | None = None
 ) -> "Cache":
     """Create a cache implementation based on the given configuration.
 

{graphrag_cache-3.0.1 → graphrag_cache-3.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphrag-cache"
-version = "3.0.1"
+version = "3.0.3"
 description = "GraphRAG cache package."
 authors = [
     {name = "Alonso Guevara Fernández", email = "alonsog@microsoft.com"},
@@ -31,8 +31,8 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "graphrag-common==3.0.1",
-    "graphrag-storage==3.0.1",
+    "graphrag-common==3.0.2",
+    "graphrag-storage==3.0.2",
 ]
 
 [project.urls]

graphrag_cache-3.0.1/README.md

@@ -1,109 +0,0 @@
-# GraphRAG Cache
-
-This package contains a collection of utilities to handle GraphRAG caching implementation.
-
-### Basic
-
-This example shows how to create a JSON cache with file storage using the GraphRAG cache package's configuration system. 
-
-```python
-import asyncio
-from graphrag_storage import StorageConfig, create_storage, StorageType
-from graphrag_cache import CacheConfig, create_cache, CacheType, create_cache_key
-
-async def run():
-    cache = create_cache()
-
-    # The above is equivalent to the following:
-    cache = create_cache(
-        CacheConfig(
-            type=CacheType.Json,
-            storage=StorageConfig(
-                type=StorageType.File,
-                base_dir="cache"
-            )
-        ),
-    )
-
-    await cache.set("my_key", {"some": "object to cache"})
-    print(await cache.get("my_key"))
-
-    # create cache key from data dict.
-    cache_key = create_cache_key({
-        "some_arg": "some_value",
-        "something_else": 5
-    })
-    await cache.set(cache_key, {"some": "object to cache"})
-    print(await cache.get(cache_key))
-
-if __name__ == "__main__":
-    asyncio.run(run())
-```
-
-### Custom Cache
-
-This demonstrates how to create a custom cache implementation by extending the base Cache class and registering it with the GraphRAG cache system. Once registered, the custom cache can be instantiated through the factory pattern using either CacheConfig or directly via cache_factory, allowing for extensible caching solutions tailored to specific needs.
-
-```python
-import asyncio
-from typing import Any
-from graphrag_storage import Storage
-from graphrag_cache import Cache, CacheConfig, create_cache, register_cache
-
-class MyCache(Cache):
-    def __init__(self, some_setting: str, optional_setting: str = "default setting", **kwargs: Any):
-        # Validate settings and initialize
-        # View the JsonCache implementation to see how to create a cache that relies on a Storage provider.
-        ...
-
-    #Implement rest of interface
-    ...
-
-register_cache("MyCache", MyCache)
-
-async def run():
-    cache = create_cache(
-        CacheConfig(
-            type="MyCache",
-            some_setting="My Setting"
-        )
-    )
-
-    # Or use the factory directly to instantiate with a dict instead of using
-    # CacheConfig + create_factory
-    # from graphrag_cache.cache_factory import cache_factory
-    # cache = cache_factory.create(strategy="MyCache", init_args={"some_setting": "My Setting"})
-
-    await cache.set("my_key", {"some": "object to cache"})
-    print(await cache.get("my_key"))
-
-if __name__ == "__main__":
-    asyncio.run(run())
-```
-
-#### Details
-
-By default, the `create_cache` comes with the following cache providers registered that correspond to the entries in the `CacheType` enum. 
-
-- `JsonCache`
-- `MemoryCache`
-- `NoopCache`
-
-The preregistration happens dynamically, e.g., `JsonCache` is only imported and registered if you request a `JsonCache` with `create_cache(CacheType.Json, ...)`. There is no need to manually import and register builtin cache providers when using `create_cache`.
-
-If you want a clean factory with no preregistered cache providers then directly import `cache_factory` and bypass using `create_cache`. The downside is that `cache_factory.create` uses a dict for init args instead of the strongly typed `CacheConfig` used with `create_cache`.
-
-```python
-from graphrag_cache.cache_factory import cache_factory
-from graphrag_cache.json_cache import JsonCache
-
-# cache_factory has no preregistered providers so you must register any
-# providers you plan on using.
-# May also register a custom implementation, see above for example.
-cache_factory.register("my_cache_impl", JsonCache)
-
-cache = cache_factory.create(strategy="my_cache_impl", init_args={"some_setting": "..."})
-
-...
-
-```