feat: add redis backend for ObjectStore (#164)

* test: add object store integration tests

* chore: license headers

Author: mathislucka

pyproject.toml

@@ -64,6 +64,7 @@ dev = [
     "pytest",
     "pytest-asyncio",
     "python-dotenv",
+    "docker"
 ]
 lint = [
     "ruff",

src/deepset_mcp/tools/tokonomics/__init__.py

@@ -13,7 +13,7 @@
 Key Features:
 - TTL-based object storage for temporary results
 - Rich object exploration with multiple rendering modes
-- Reference-based parameter passing (@obj_001.path.to.value)
+- Reference-based parameter passing (@obj_id.path.to.value)
 - Type-safe decorators that preserve function signatures
 - Configurable preview truncation and custom rendering callbacks
 
@@ -30,7 +30,7 @@
     >>>
     >>> result = get_data()
     >>> print(result)  # Shows rich preview
-    >>> result.obj_id  # "obj_001"
+    >>> result.obj_id  # "obj_123"
     >>> result.value   # Original data
 
 Referenceable tool that accepts references:
@@ -45,28 +45,27 @@
     >>> process_users([{"name": "Bob"}])
     >>>
     >>> # Use with reference
-    >>> process_users("@obj_001.users")
+    >>> process_users("@obj_123.users")
 
 Exploration utilities:
 
     >>> from deepset_mcp.tools.tokonomics import explore, search
     >>>
     >>> # Explore object structure
-    >>> explore("obj_001", mode="tree")
+    >>> explore("obj_123", mode="tree")
     >>>
     >>> # Search within objects
-    >>> search("obj_001", "Alice")
+    >>> search("obj_123", "Alice")
 """
 
 from .decorators import explorable, explorable_and_referenceable, referenceable
 from .explorer import RichExplorer
-from .object_store import Explorable, InMemoryBackend, ObjectRef, ObjectStore
+from .object_store import Explorable, InMemoryBackend, ObjectStore
 
 __all__ = [
     # Core classes
     "Explorable",
     "InMemoryBackend",
-    "ObjectRef",
     "ObjectStore",
     "RichExplorer",
     # Decorators

src/deepset_mcp/tools/tokonomics/decorators.py

@@ -19,15 +19,15 @@
 
 from glom import GlomError, glom
 
-from .explorer import RichExplorer
-from .object_store import Explorable, ObjectRef, ObjectStore
+from deepset_mcp.tools.tokonomics.explorer import RichExplorer
+from deepset_mcp.tools.tokonomics.object_store import Explorable, ObjectStore
 
 F = TypeVar("F", bound=Callable[..., Any])
 
 
 def _is_reference(value: Any) -> bool:
     """Check if a value is a reference string."""
-    return isinstance(value, str) and ObjectRef.parse(value) is not None
+    return isinstance(value, str) and value.startswith("@") and len(value) > 1
 
 
 def _type_allows_str(annotation: Any) -> bool:
@@ -87,10 +87,10 @@ def _enhance_docstring_for_references(original: str, param_info: dict[str, dict[
             f"    {func_name}(data={{'key': 'value'}}, threshold=10)",
             "",
             "    # Call with references",
-            f"    {func_name}(data='@obj_001', threshold='@obj_002.config.threshold')",
+            f"    {func_name}(data='@obj_123', threshold='@obj_456.config.threshold')",
             "",
             "    # Mixed call",
-            f"    {func_name}(data='@obj_001.items', threshold=10)",
+            f"    {func_name}(data='@obj_123.items', threshold=10)",
         ]
     )
 
@@ -141,7 +141,7 @@ def explorable(
     ...     return {"processed": data}
     ...
     >>> result = process_data({"input": "value"})
-    >>> # result contains a preview and object ID like "@obj_001"
+    >>> # result contains a preview and object ID like "@obj_123"
     """
 
     def decorator(func: F) -> F:
@@ -180,7 +180,7 @@ def referenceable(
 ) -> Callable[[F], F]:
     """Decorator factory that enables parameters to accept object references.
 
-    Parameters can accept reference strings like '@obj_001' or '@obj_001.path.to.value'
+    Parameters can accept reference strings like '@obj_id' or '@obj_id.path.to.value'
     which are automatically resolved before calling the function.
 
     :param object_store: The object store instance to use for lookups.
@@ -200,27 +200,25 @@ def referenceable(
     >>> process_data({"a": 1, "b": 2}, 10)
     >>>
     >>> # Call with references
-    >>> process_data("@obj_001", "@obj_002.config.threshold")
+    >>> process_data("@obj_123", "@obj_456.config.threshold")
     """
 
     def resolve_reference(ref_str: str) -> Any:
         """Resolve a reference string to its actual value."""
-        ref = ObjectRef.parse(ref_str)
-        if ref is None:
-            raise ValueError(f"Invalid reference format: {ref_str}")
+        obj_id, path = explorer.parse_reference(ref_str)
 
-        obj = object_store.get(ref.obj_id)
+        obj = object_store.get(obj_id)
         if obj is None:
-            raise ValueError(f"Object @{ref.obj_id} not found or expired")
+            raise ValueError(f"Object @{obj_id} not found or expired")
 
-        if ref.path:
+        if path:
             try:
-                explorer._validate_path(ref.path)
-                return glom(obj, explorer._parse_path(ref.path))
+                explorer._validate_path(path)
+                return glom(obj, explorer._parse_path(path))
             except GlomError as exc:
-                raise ValueError(f"Navigation error at {ref.path}: {exc}") from exc
+                raise ValueError(f"Navigation error at {path}: {exc}") from exc
             except ValueError as exc:
-                raise ValueError(f"Invalid path {ref.path}: {exc}") from exc
+                raise ValueError(f"Invalid path {path}: {exc}") from exc
 
         return obj
 
@@ -362,7 +360,7 @@ def explorable_and_referenceable(
     ...     return {**data1, **data2}
     ...
     >>> # Accepts references and returns preview with object ID
-    >>> result = merge_data("@obj_001", {"new": "data"})
+    >>> result = merge_data("@obj_123", {"new": "data"})
     >>> # result contains a preview and can be referenced as "@obj_002"
     """
 

src/deepset_mcp/tools/tokonomics/explorer.py

@@ -18,7 +18,7 @@
 from rich.console import Console
 from rich.pretty import Pretty
 
-from .object_store import ObjectRef, ObjectStore
+from deepset_mcp.tools.tokonomics.object_store import ObjectStore
 
 
 class RichExplorer:
@@ -58,11 +58,26 @@ def __init__(
         # Validation pattern for allowed attributes
         self.allowed_attr_regex = re.compile(r"[A-Za-z][A-Za-z0-9_]*\Z")
 
+    def parse_reference(self, ref_str: str) -> tuple[str, str]:
+        """Parse @obj_id.path into (obj_id, path).
+
+        :param ref_str: Reference string like @obj_id.path or obj_id
+        :return: Tuple of (obj_id, path)
+        """
+        if not ref_str.startswith("@"):
+            return ref_str, ""  # Not a reference, return as-is
+
+        ref_str = ref_str[1:]  # Remove @
+        if "." in ref_str:
+            obj_id, path = ref_str.split(".", 1)
+            return obj_id, path
+        return ref_str, ""
+
     def explore(self, obj_id: str, path: str = "") -> str:
         """Return a string preview of the requested object.
 
         :param obj_id: Identifier obtained from the store.
-        :param path: Navigation path using ``.`` or ``[...]`` notation (e.g. ``@obj_001.path.to.attribute``).
+        :param path: Navigation path using ``.`` or ``[...]`` notation (e.g. ``@obj_id.path.to.attribute``).
         :return: String representation of the object.
         """
         obj = self._get_object_at_path(obj_id, path)
@@ -187,12 +202,11 @@ def _get_object_at_path(self, obj_id: str, path: str) -> Any:
         :param path: Navigation path (optional).
         :return: Object at path or error string.
         """
-        ref = ObjectRef.parse(obj_id)
-        # We accept @obj_001 as well as obj_001
-        if ref is None:
-            resolved_obj_id = obj_id
-        else:
-            resolved_obj_id = ref.obj_id
+        resolved_obj_id, ref_path = self.parse_reference(obj_id)
+
+        # If there's a path from the reference, combine it with the provided path
+        if ref_path:
+            path = f"{ref_path}.{path}" if path else ref_path
 
         obj = self.store.get(resolved_obj_id)
         if obj is None:

src/deepset_mcp/tools/tokonomics/object_store.py

@@ -21,7 +21,6 @@
 from __future__ import annotations
 
 import logging
-import re
 import time
 import uuid
 from typing import (
@@ -229,42 +228,3 @@ def get(self, obj_id: str) -> Any | None:
     def delete(self, obj_id: str) -> bool:
         """Delete object."""
         return self._backend.delete(obj_id)
-
-
-# =============================================================================
-# 4 · Object references
-# =============================================================================
-
-
-class ObjectRef:
-    """Lightweight parser for reference strings of the form.
-
-    Examples::
-
-        @obj_042.settings.theme
-        @obj_123["settings"]["theme"]
-    """
-
-    _PATTERN = re.compile(r"^@(\w+)(.*)$")
-
-    def __init__(self, obj_id: str, path: str = "") -> None:
-        """Initialize ObjectRef with object ID and optional path."""
-        self.obj_id = obj_id
-        self.path = path
-
-    # --------------------------------------------------------------------- #
-    # Factory
-    # --------------------------------------------------------------------- #
-
-    @classmethod
-    def parse(cls, ref: str | Any) -> ObjectRef | None:
-        """Parse a reference string into an ObjectRef instance."""
-        if not isinstance(ref, str):
-            return None
-        m = cls._PATTERN.match(ref)
-        if m is None:
-            return None
-        obj_id, path = m.group(1), m.group(2) or ""
-        if path.startswith("."):
-            path = path[1:]
-        return cls(obj_id, path)

test/integration/tools/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+

test/integration/tools/tokonomics/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+