deepset-mcp 0.0.2__py3-none-any.whl

deepset_mcp/tools/tokonomics/explorer.py

@@ -0,0 +1,347 @@
+"""
+Rich Explorer for Object Exploration and Rendering.
+
+Presents Python objects in various Rich formats and supports basic
+navigation, searching, and slicing.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from glom import GlomError, Path, T, glom
+from rich.console import Console
+from rich.pretty import Pretty
+
+from .object_store import ObjectRef, ObjectStore
+
+
+class RichExplorer:
+    """Presents Python objects in various Rich formats with navigation support.
+
+    :param store: Object store used for lookups.
+    :param max_items: Maximum number of items to show for lists and nested collections (default: 20).
+                      Note: All keys are shown for top-level dicts.
+    :param max_string_length: Maximum string length before truncation (default: 300).
+    :param max_depth: Maximum depth for object representation (default: 3).
+    :param max_search_matches: Maximum number of search matches to display (default: 10).
+    :param search_context_length: Number of characters to show around search matches (default: 150).
+    """
+
+    def __init__(
+        self,
+        store: ObjectStore,
+        max_items: int = 25,
+        max_string_length: int = 300,
+        max_depth: int = 4,
+        max_search_matches: int = 10,
+        search_context_length: int = 150,
+    ) -> None:
+        """Initialize the RichExplorer with storage and configuration options."""
+        self.store = store
+        self.console = Console(force_terminal=False, width=120)
+
+        # Display limits
+        self.max_items = max_items
+        self.max_string_length = max_string_length
+        self.max_depth = max_depth
+
+        # Search configuration
+        self.max_search_matches = max_search_matches
+        self.search_context_length = search_context_length
+
+        # Validation pattern for allowed attributes
+        self.allowed_attr_regex = re.compile(r"[A-Za-z][A-Za-z0-9_]*\Z")
+
+    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``).
+        :return: String representation of the object.
+        """
+        obj = self._get_object_at_path(obj_id, path)
+
+        # Generate header and body
+        header = self._make_header(obj_id, path, obj)
+
+        # We want the full length str if the (nested) object is a string
+        if isinstance(obj, str):
+            body = obj
+        else:
+            body = self._get_pretty_repr(obj)
+
+        return f"{header}\n\n{body}"
+
+    def search(self, obj_id: str, pattern: str, path: str = "", case_sensitive: bool = False) -> str:
+        """Search for a pattern within a string object.
+
+        :param obj_id: Identifier obtained from the store.
+        :param pattern: Regular expression pattern to search for.
+        :param path: Navigation path to search within (optional).
+        :param case_sensitive: Whether search should be case sensitive.
+        :return: Search results as formatted string.
+        """
+        obj = self._get_object_at_path(obj_id, path)
+
+        # Generate header
+        header = self._make_header(obj_id, path, obj)
+
+        # Only allow search on strings
+        if not isinstance(obj, str):
+            return f"{header}\n\nSearch is only supported on string objects. Found {type(obj).__name__} at path."
+
+        # Search the string
+        flags = 0 if case_sensitive else re.IGNORECASE
+
+        try:
+            matches = list(re.finditer(pattern, obj, flags))
+        except re.error as e:
+            return f"{header}\n\nInvalid regex pattern: {e}"
+
+        if not matches:
+            return f"{header}\n\nNo matches found for pattern '{pattern}'"
+
+        # Format results
+        result = [f"Found {len(matches)} matches for pattern '{pattern}':", ""]
+
+        # Show limited number of matches
+        for i, match in enumerate(matches[: self.max_search_matches]):
+            start, end = match.span()
+            context_start = max(0, start - self.search_context_length)
+            context_end = min(len(obj), end + self.search_context_length)
+            context = obj[context_start:context_end]
+
+            # Highlight the match
+            match_in_context = start - context_start
+            highlighted = (
+                context[:match_in_context]
+                + f"[{context[match_in_context : match_in_context + (end - start)]}]"
+                + context[match_in_context + (end - start) :]
+            )
+            result.append(f"Match {i + 1}: ...{highlighted}...")
+
+        if len(matches) > self.max_search_matches:
+            result.append(f"\n... and {len(matches) - self.max_search_matches} more matches")
+
+        return f"{header}\n\n" + "\n".join(result)
+
+    def slice(self, obj_id: str, start: int = 0, end: int | None = None, path: str = "") -> str:
+        """Extract a slice from a string or list object.
+
+        :param obj_id: Identifier of the object.
+        :param start: Start index for slicing.
+        :param end: End index for slicing (None for end of sequence).
+        :param path: Navigation path to object to slice (optional).
+        :return: String representation of the slice.
+        """
+        obj = self._get_object_at_path(obj_id, path)
+
+        # Generate header
+        header = self._make_header(obj_id, path, obj)
+
+        # Handle string slicing
+        if isinstance(obj, str):
+            sliced: str | list[Any] | tuple[Any] = obj[start:end]
+            actual_end = end if end is not None else len(obj)
+            body = f"String slice [{start}:{actual_end}] of length {len(sliced)}:\n\n{sliced}"
+            return f"{header}\n\n{body}"
+
+        # Handle list/tuple slicing
+        elif isinstance(obj, list | tuple):
+            sliced = obj[start:end]
+            actual_end = end if end is not None else len(obj)
+
+            # Use Pretty to render the sliced list with current settings
+            with self.console.capture() as cap:
+                self.console.print(
+                    Pretty(
+                        sliced,
+                        max_depth=self.max_depth,
+                        max_length=None,  # Show all items in the slice
+                        max_string=self.max_string_length,
+                        overflow="ellipsis",
+                    )
+                )
+
+            type_name = type(obj).__name__
+            body = (
+                f"{type_name.capitalize()} slice [{start}:{actual_end}] "
+                f"(showing {len(sliced)} of {len(obj)} items):\n\n"
+                f"{cap.get().rstrip()}"
+            )
+            return f"{header}\n\n{body}"
+
+        else:
+            return f"{header}\n\nObject of type {type(obj).__name__} does not support slicing"
+
+    def _get_object_at_path(self, obj_id: str, path: str) -> Any:
+        """Get object from store and navigate to path if provided.
+
+        :param obj_id: Identifier obtained from the store.
+        :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
+
+        obj = self.store.get(resolved_obj_id)
+        if obj is None:
+            raise ValueError(f"Object {obj_id} not found or expired.")
+
+        if path:
+            self._validate_path(path)
+            try:
+                obj = glom(obj, self._parse_path(path))
+            except GlomError as e:
+                raise ValueError(f"Object '{obj_id}' does not have a value at path '{path}'.") from e
+
+        return obj
+
+    def _validate_path(self, path: str) -> None:
+        """Ensure every attribute component matches the allow-list regex.
+
+        :param path: Path string to validate.
+        :raises ValueError: If path contains disallowed attributes.
+        """
+        for part in re.split(r"[.\[\]]+", path):
+            if not part or part.isdigit():
+                continue
+            # Strip quotes for string keys
+            part = part.strip("\"'")
+            if not self.allowed_attr_regex.match(part):
+                raise ValueError(f"Access to attribute '{part}' is not permitted")
+
+    def _parse_path(self, path: str) -> Any:
+        """Parse a path string into a glom spec.
+
+        :param path: Path string in dot/bracket notation.
+        :return: Glom spec for navigation.
+        """
+        if not path:
+            return T
+
+        parts: list[Any] = []
+        current = ""
+        in_brackets = False
+
+        for char in path:
+            if char == "[":
+                if current:
+                    parts.append(current)
+                    current = ""
+                in_brackets = True
+            elif char == "]":
+                if current:
+                    # Try to parse as int for list indices
+                    try:
+                        parts.append(int(current))
+                    except ValueError:
+                        # String key for dicts
+                        parts.append(current.strip("\"'"))
+                    current = ""
+                in_brackets = False
+            elif char == "." and not in_brackets:
+                if current:
+                    parts.append(current)
+                    current = ""
+            else:
+                current += char
+
+        if current:
+            parts.append(current)
+
+        return Path(*parts) if len(parts) > 1 else parts[0]
+
+    def _make_header(self, obj_id: str, path: str, obj: Any) -> str:
+        """Create a header showing object info.
+
+        :param obj_id: Object identifier.
+        :param path: Navigation path.
+        :param obj: The object being displayed.
+        :return: Formatted header string.
+        """
+        type_name = type(obj).__name__
+        if hasattr(obj, "__module__") and obj.__module__ not in ("builtins", "__main__"):
+            type_name = f"{obj.__module__}.{type_name}"
+
+        location = f"@{obj_id}" + (f".{path}" if path else "")
+
+        # Add size info for sized objects
+        size_info = ""
+        if hasattr(obj, "__len__"):
+            try:
+                size_info = f" (length: {len(obj)})"
+            except Exception:
+                pass
+
+        return f"{location} → {type_name}{size_info}"
+
+    def _get_pretty_repr(self, obj: Any) -> str:
+        """Get Rich pretty representation of object.
+
+        :param obj: Object to represent.
+        :return: String representation using Rich Pretty.
+        """
+        # Special handling for top-level dicts to show all keys
+        if isinstance(obj, dict):
+            if not obj:
+                return "{}"
+
+            # Pretty print each value separately with max_items applied
+            result_parts = ["{"]
+
+            for key, value in obj.items():
+                # Pretty print the key
+                with self.console.capture() as key_cap:
+                    self.console.print(Pretty(key), end="")
+                key_str = key_cap.get().rstrip()
+
+                # Pretty print the value with limits applied
+                with self.console.capture() as val_cap:
+                    self.console.print(
+                        Pretty(
+                            value,
+                            max_depth=self.max_depth - 1,  # Reduce depth since we're already one level in
+                            max_length=self.max_items,
+                            max_string=self.max_string_length,
+                            expand_all=True,
+                            overflow="ellipsis",
+                        ),
+                        end="",
+                    )
+                val_str = val_cap.get().rstrip()
+
+                # Handle multiline values
+                if "\n" in val_str:
+                    # Indent continuation lines
+                    lines = val_str.split("\n")
+                    val_str = lines[0] + "\n" + "\n".join("        " + line for line in lines[1:])
+
+                result_parts.append(f"    {key_str}: {val_str},")
+
+            # Remove trailing comma from last item
+            if result_parts[-1].endswith(","):
+                result_parts[-1] = result_parts[-1][:-1]
+
+            result_parts.append("}")
+            return "\n".join(result_parts)
+
+        # Regular pretty print for non-dict objects
+        with self.console.capture() as cap:
+            self.console.print(
+                Pretty(
+                    obj,
+                    max_depth=self.max_depth,
+                    max_length=self.max_items,
+                    max_string=self.max_string_length,
+                    expand_all=True,
+                    overflow="ellipsis",
+                )
+            )
+        return cap.get().rstrip()

deepset_mcp/tools/tokonomics/object_store.py

@@ -0,0 +1,177 @@
+"""
+Tokonomics: Explorable and Referenceable Tools.
+
+===============================================
+
+A library that equips LLM‑agents with:
+
+* TTL‑based object storage
+* Rich object exploration & reference passing
+* Smart decorators for explorable outputs and referenceable inputs
+* Strict typing / signature preservation (incl. *async* callables)
+* ReST‑style docstring enhancement
+* Configurable preview truncation (`max_bytes`) and a user‑supplied
+  `preview_callback` for custom renderings (e.g. pandas.DataFrame)
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import (
+    Any,
+    Generic,
+    TypeVar,
+)
+
+# =============================================================================
+# 1 · Generic return‑value wrapper
+# =============================================================================
+
+_T = TypeVar("_T")
+
+
+class Explorable(Generic[_T]):
+    """
+    Wrapper returned by ``@explorable`` decorated tools.
+
+    Attributes
+    ----------
+    obj_id :
+        The internal identifier of the stored object.
+    value :
+        The original, *unmodified* object returned by the wrapped tool.
+    preview :
+        Rich‑rendered string generated by the explorer.
+    """
+
+    __slots__ = ("obj_id", "value", "_preview")
+
+    def __init__(self, obj_id: str, value: _T, preview: str) -> None:
+        """Initialize Explorable wrapper with object ID, value, and preview."""
+        self.obj_id = obj_id
+        self.value: _T = value
+        self._preview = preview
+
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+    # Representations
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+    def __str__(self) -> str:
+        """Return the preview string representation."""
+        return self._preview
+
+    __repr__ = __str__
+
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+    # Convenience for notebooks / REPLs
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+    _ipython_display_ = __str__  # Jupyter friendly
+
+
+# =============================================================================
+# 2 · Time‑to‑live based object store
+# =============================================================================
+
+
+class ObjectStore:
+    """
+    Very small in‑memory store with TTL‑based eviction.
+
+    Parameters
+    ----------
+    ttl :
+        Default time‑to‑live in **seconds** for every stored entry.  The TTL is
+        evaluated lazily on every ``get`` / ``put``.  A value of ``0`` disables
+        expiry (mainly for tests).
+    """
+
+    def __init__(self, ttl: float = 3_600.0) -> None:
+        """Initialize ObjectStore with TTL in seconds."""
+        self._ttl: float = float(ttl)
+        self._objects: dict[str, tuple[Any, float]] = {}
+        self._counter: int = 0
+
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––
+    # Internal helpers
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+    def _now(self) -> float:
+        return time.time()
+
+    def _evict_expired(self) -> None:
+        if self._ttl == 0:
+            return
+        expiry_threshold = self._now() - self._ttl
+        expired = [k for k, (_, ts) in self._objects.items() if ts < expiry_threshold]
+        for k in expired:
+            del self._objects[k]
+
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––
+    # Public API
+    # ––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+    def put(self, obj: Any) -> str:
+        """Store *obj* and return its new reference id (``obj_001`` …)."""
+        self._evict_expired()
+        self._counter += 1
+        obj_id = f"obj_{self._counter:03d}"
+        self._objects[obj_id] = (obj, self._now())
+        return obj_id
+
+    def get(self, obj_id: str) -> Any | None:
+        """Retrieve *obj* by id.
+
+        Returns ``None`` if the object does not exist or has expired.
+        """
+        self._evict_expired()
+        entry = self._objects.get(obj_id)
+        return None if entry is None else entry[0]
+
+    def delete(self, obj_id: str) -> bool:
+        """Remove object from the store.
+
+        Returns ``True`` if the object was present.
+        """
+        self._evict_expired()
+        return self._objects.pop(obj_id, None) is not None
+
+
+# =============================================================================
+# 3 · 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)

deepset_mcp/tools/workspace.py

@@ -0,0 +1,61 @@
+"""Tools for interacting with workspaces."""
+
+from deepset_mcp.api.exceptions import BadRequestError, ResourceNotFoundError, UnexpectedAPIError
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.shared_models import NoContentResponse
+from deepset_mcp.api.workspace.models import Workspace, WorkspaceList
+
+
+async def list_workspaces(*, client: AsyncClientProtocol) -> WorkspaceList | str:
+    """Retrieves a list of all workspaces available to the user.
+
+    This tool provides an overview of all workspaces that the user has access to.
+    Each workspace contains information about its name, ID, supported languages,
+    and default idle timeout settings.
+
+    :param client: The async client for API communication.
+    :returns: List of workspaces or error message.
+    """
+    try:
+        return await client.workspaces().list()
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to list workspaces: {e}"
+
+
+async def get_workspace(*, client: AsyncClientProtocol, workspace_name: str) -> Workspace | str:
+    """Fetches detailed information for a specific workspace by name.
+
+    This tool retrieves comprehensive details about a specific workspace, including
+    its unique ID, supported languages, and configuration settings. Use this when
+    you need detailed information about a particular workspace.
+
+    :param client: The async client for API communication.
+    :param workspace_name: The name of the workspace to fetch details for.
+    :returns: Workspace details or error message.
+    """
+    try:
+        return await client.workspaces().get(workspace_name=workspace_name)
+    except ResourceNotFoundError:
+        return f"There is no workspace named '{workspace_name}'."
+    except (BadRequestError, UnexpectedAPIError) as e:
+        return f"Failed to fetch workspace '{workspace_name}': {e}"
+
+
+async def create_workspace(*, client: AsyncClientProtocol, name: str) -> NoContentResponse | str:
+    """Creates a new workspace with the specified name.
+
+    This tool creates a new workspace that can be used to organize pipelines,
+    indexes, and other resources. The workspace name must be unique across
+    the platform. Once created, you can start deploying pipelines and other
+    resources within this workspace.
+
+    :param client: The async client for API communication.
+    :param name: The name for the new workspace. Must be unique.
+    :returns: Success confirmation or error message.
+    """
+    try:
+        return await client.workspaces().create(name=name)
+    except BadRequestError as e:
+        return f"Failed to create workspace '{name}': {e}"
+    except UnexpectedAPIError as e:
+        return f"Failed to create workspace '{name}': {e}"