lmcache-cli 0.4.5.dev0__py3-none-any.whl

lmcache/__init__.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Any
+import importlib
+import sys
+
+# First Party
+from lmcache.logging import init_logger
+
+try:
+    # First Party
+    from lmcache._version import __version__
+except ImportError:
+    __version__ = "unknown"
+
+logger = init_logger(__name__)
+__all__ = ["__version__"]
+
+
+# --------------------------
+# Dynamic backend selection
+# --------------------------
+def _get_backend() -> Any:
+    """
+    Try backends in order, first successful import wins.
+    """
+    # Third Party
+    import torch
+
+    backend_candidates = [
+        (
+            "lmcache.c_ops",
+            "cuda_ops",
+            lambda: torch.cuda.is_available(),
+        ),
+        # should extend to more HWs..
+    ]
+
+    imported = False
+    module = None
+    for module_name, backend_name, predicate in backend_candidates:
+        # 1 Check whether the backend is available before importing
+        try:
+            if not predicate():
+                logger.info(
+                    "Skipping backend %s: predicate returned False",
+                    module_name,
+                )
+                continue
+        except Exception as e:
+            logger.warning(
+                "Skipping backend %s: predicate raised error: %s",
+                module_name,
+                e,
+            )
+            continue
+        # 2 Run availability check for the backend
+        try:
+            module = importlib.import_module(module_name)
+            logger.info("Using backend: %s", module_name)
+            imported = True
+            break
+        except Exception as e:
+            logger.warning("Failed to import backend %s: %s", module_name, e)
+
+    if not imported:
+        try:
+            logger.warning("Fallback to python backend lmcache.non_cuda_equivalents")
+            module = importlib.import_module("lmcache.non_cuda_equivalents")
+            logger.info("Using backend: lmcache.non_cuda_equivalents")
+        except ImportError as e:
+            raise ImportError("No backend could be imported for lmcache.") from e
+    return module
+
+
+# --------------------------
+# Backend instance
+# --------------------------
+try:
+    _ops = _get_backend()
+    sys.modules["lmcache.c_ops"] = _ops
+except (ImportError, ModuleNotFoundError):
+    logger.debug("No compute backend loaded; CLI-only mode (torch/numba not installed)")

lmcache/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.4.5.dev0'
+__version_tuple__ = version_tuple = (0, 4, 5, 'dev0')
+
+__commit_id__ = commit_id = 'g6fbec463e'

lmcache/cli/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

lmcache/cli/commands/__init__.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CLI subcommand package.
+
+To add a new command:
+
+1. Create a module with a :class:`BaseCommand` subclass.
+2. Add one import + one entry to :data:`ALL_COMMANDS` below.
+"""
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.bench import BenchCommand
+from lmcache.cli.commands.describe import DescribeCommand
+from lmcache.cli.commands.kvcache import KVCacheCommand
+from lmcache.cli.commands.mock import MockCommand
+from lmcache.cli.commands.ping import PingCommand
+from lmcache.cli.commands.query import QueryCommand
+from lmcache.cli.commands.server import ServerCommand
+from lmcache.cli.commands.tool import ToolCommand
+from lmcache.cli.commands.trace import TraceCommand
+
+ALL_COMMANDS: list[BaseCommand] = [
+    MockCommand(),
+    KVCacheCommand(),
+    DescribeCommand(),
+    PingCommand(),
+    QueryCommand(),
+    ServerCommand(),
+    BenchCommand(),
+    ToolCommand(),
+    TraceCommand(),
+]
+
+__all__ = ["ALL_COMMANDS", "BaseCommand"]

lmcache/cli/commands/base.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract base class and shared helpers for CLI subcommands."""
+
+# Standard
+import abc
+import argparse
+
+# First Party
+from lmcache.cli.metrics import (
+    FileHandler,
+    Metrics,
+    StreamHandler,
+    get_formatter,
+)
+
+
+class BaseCommand(abc.ABC):
+    """Abstract base class that all CLI subcommands must inherit from.
+
+    Subclasses must implement :meth:`name`, :meth:`help`,
+    :meth:`add_arguments`, and :meth:`execute`.  The :meth:`register`
+    method wires everything together automatically.
+
+    Example::
+
+        class PingCommand(BaseCommand):
+            def name(self) -> str:
+                return "ping"
+
+            def help(self) -> str:
+                return "Ping the KV cache server."
+
+            def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+                parser.add_argument("--url", required=True)
+
+            def execute(self, args: argparse.Namespace) -> None:
+                metrics = self.create_metrics("Ping Result", args)
+                metrics.add("status", "Status", "OK")
+                metrics.emit()
+    """
+
+    @abc.abstractmethod
+    def name(self) -> str:
+        """Return the subcommand name (e.g. ``"mock"``)."""
+
+    @abc.abstractmethod
+    def help(self) -> str:
+        """Return short help text shown by ``lmcache -h``."""
+
+    @abc.abstractmethod
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add command-specific arguments to *parser*.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+
+    @abc.abstractmethod
+    def execute(self, args: argparse.Namespace) -> None:
+        """Execute the subcommand.
+
+        Called by the CLI dispatcher in ``main.py`` via
+        ``args.func(args)`` after argument parsing.  The
+        :meth:`register` method binds this as the dispatch target
+        using ``parser.set_defaults(func=self.execute)``.
+
+        Args:
+            args: Parsed CLI arguments.
+        """
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        """Register this command with the CLI argument parser.
+
+        This method is not typically overridden.  It calls
+        :meth:`name`, :meth:`help`, and :meth:`add_arguments`, then
+        binds :meth:`execute` as the dispatch target.
+
+        Args:
+            subparsers: The subparsers action from the root parser.
+        """
+        parser = subparsers.add_parser(self.name(), help=self.help())
+        self.add_arguments(parser)
+        _add_output_args(parser)
+        parser.set_defaults(func=self.execute)
+
+    def create_metrics(
+        self,
+        title: str,
+        args: argparse.Namespace,
+        width: int = 48,
+    ) -> Metrics:
+        """Create a :class:`Metrics` with default handlers pre-registered.
+
+        Handlers are configured from ``args.format``, ``args.output``,
+        and ``args.quiet``:
+
+        * A :class:`StreamHandler` writing to stdout, unless ``--quiet``
+          is set. The formatter is determined by ``--format``
+          (default: ``terminal``).
+        * A :class:`FileHandler` if ``--output`` is set (uses the same
+          formatter chosen by ``--format``).
+
+        Args:
+            title: Report title.
+            args: Parsed CLI arguments (inspects ``format`` and ``output``).
+            width: Character width for terminal rendering (only used by
+                formatters that support it, e.g. ``TerminalFormatter``).
+
+        Returns:
+            A ready-to-use ``Metrics`` instance.
+        """
+        metrics = Metrics(title=title)
+
+        quiet = getattr(args, "quiet", False)
+        fmt_name = getattr(args, "format", None) or "terminal"
+        if not quiet:
+            metrics.add_handler(StreamHandler(get_formatter(fmt_name, width=width)))
+
+        output = getattr(args, "output", None)
+        if output:
+            metrics.add_handler(
+                FileHandler(output, get_formatter(fmt_name, width=width))
+            )
+
+        return metrics
+
+
+def _add_output_args(parser: argparse.ArgumentParser) -> None:
+    """Add the common ``--format`` and ``--output`` flags.
+
+    Called automatically by :meth:`BaseCommand.register` — subcommands
+    do not need to call this themselves.
+
+    Args:
+        parser: The ``ArgumentParser`` to add the flags to.
+    """
+    parser.add_argument(
+        "--format",
+        type=str,
+        default=None,
+        metavar="FORMAT",
+        help=("Stdout output format (default: terminal). Available: terminal, json."),
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        metavar="PATH",
+        help="Save metrics to a file at PATH (format chosen by --format).",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        default=False,
+        help="Suppress stdout output. Exit code only.",
+    )