lmcache-cli 0.4.6.dev0__py3-none-any.whl → 0.4.8.dev21__py3-none-any.whl

lmcache/__init__.py

@@ -4,6 +4,7 @@
 from typing import Any
 import importlib
 import sys
+import types
 
 # First Party
 from lmcache.logging import init_logger
@@ -30,10 +31,8 @@ def _detect_device() -> tuple[Any, str]:
 
     Returns:
         tuple[Any, str]: A tuple of (torch_device_module, device_type_string),
-            e.g. ``(torch.cuda, "cuda")`` or ``(torch.xpu, "xpu")``.
-
-    Raises:
-        RuntimeError: If no supported accelerator is found (checked CUDA, XPU, HPU).
+            e.g. ``(torch.cuda, "cuda")``, ``(torch.musa, "musa")``, or
+            ``(torch.xpu, "xpu")``.
     """
     try:
         # Third Party
@@ -41,18 +40,27 @@ def _detect_device() -> tuple[Any, str]:
     except ImportError:
         return None, "cpu"  # fallback，CLI-only
 
-    if hasattr(torch, "xpu") and torch.xpu.is_available():
+    if hasattr(torch, "musa") and torch.musa.is_available():  # type: ignore[attr-defined]
+        logger.info("MUSA device is available. Using MUSA for LMCache engine.")
+        return torch.musa, "musa"  # type: ignore[attr-defined]
+    elif hasattr(torch, "xpu") and torch.xpu.is_available():
         return torch.xpu, "xpu"
     elif hasattr(torch, "hpu") and torch.hpu.is_available():
         return torch.hpu, "hpu"
-    else:
-        # Fallback: always return torch.cuda for backward compatibility
-        # with existing tests and code paths that assume CUDA is the default.
+    elif torch.cuda.is_available():
         return torch.cuda, "cuda"
+    else:
+        # First Party
+        from lmcache.v1.platform.cpu.stub_cpu_device import StubCPUDevice
+
+        # Fallback: always return torch, cpu as stub
+        return StubCPUDevice("cpu"), "cpu"
 
 
 torch_dev, torch_device_type = _detect_device()
 
+logger.info(" torch_dev=%s, torch_device_type=%s", torch_dev, torch_device_type)
+
 
 # --------------------------
 # Dynamic backend selection
@@ -61,10 +69,16 @@ def _get_backend() -> Any:
     """
     Try backends in order, first successful import wins.
     """
+    default_module = importlib.import_module("lmcache.python_ops_fallback")
     # Third Party
     import torch
 
     backend_candidates = [
+        (
+            "lmcache.xpu_ops",
+            "xpu_ops",
+            lambda: torch.xpu.is_available(),
+        ),
         (
             "lmcache.c_ops",
             "cuda_ops",
@@ -73,8 +87,6 @@ def _get_backend() -> Any:
         # 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:
@@ -93,21 +105,16 @@ def _get_backend() -> Any:
             continue
         # 2 Run availability check for the backend
         try:
-            module = importlib.import_module(module_name)
+            backend_module = importlib.import_module(module_name)
+            merged_module = types.ModuleType("lmcache.c_ops")
+            merged_module.__dict__.update(default_module.__dict__)
+            merged_module.__dict__.update(backend_module.__dict__)
             logger.info("Using backend: %s", module_name)
-            imported = True
-            break
+            return merged_module
         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
+    return default_module
 
 
 # --------------------------
@@ -115,6 +122,10 @@ def _get_backend() -> Any:
 # --------------------------
 try:
     _ops = _get_backend()
+    # override lmcache.c_ops with merged module,
+    # in which:
+    #     python_ops_fallback as base,
+    #     use backend implementation if exists
     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

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.6.dev0'
-__version_tuple__ = version_tuple = (0, 4, 6, 'dev0')
+__version__ = version = '0.4.8.dev21'
+__version_tuple__ = version_tuple = (0, 4, 8, 'dev21')
 
-__commit_id__ = commit_id = 'g168bbb976'
+__commit_id__ = commit_id = 'g5d621e1e5'

lmcache/banner.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Startup banner shown when LMCache starts serving.
+
+The banner is printed at most once per process, to ``stderr``, by the
+``lmcache`` CLI and by the vLLM connector integrations (scheduler role
+only, so tensor-parallel deployments print a single banner). Setting the
+``LMCACHE_DISABLE_BANNER=1`` environment variable suppresses it.
+"""
+
+# Standard
+from typing import TextIO
+import os
+
+try:
+    # First Party
+    from lmcache import _version
+
+    _LMCACHE_VERSION = getattr(_version, "__version__", "unknown")
+    _LMCACHE_COMMIT = getattr(_version, "__commit_id__", "")
+except ImportError:  # pragma: no cover - version file is generated at build time
+    _LMCACHE_VERSION = "unknown"
+    _LMCACHE_COMMIT = ""
+
+DISABLE_BANNER_ENV = "LMCACHE_DISABLE_BANNER"
+
+LMCACHE_WEBSITE = "https://lmcache.ai/"
+LMCACHE_RECIPES = "https://docs.lmcache.ai/recipes"
+LMCACHE_LINKEDIN = "https://www.linkedin.com/company/lmcache-lab"
+
+# Solarized palette, 24-bit ANSI escapes (TTY only): "LM" in bold italic
+# orange (#cb4b16), "Cache" in cyan (#2aa198).
+_LM_STYLE = "\x1b[1;3;38;2;203;75;22m"
+_CACHE_STYLE = "\x1b[38;2;42;161;152m"
+_DIM_STYLE = "\x1b[2m"
+_RESET = "\x1b[0m"
+
+# Figlet "standard" font, split into the two color groups.
+_LM_ART = (
+    " _     __  __ ",
+    "| |   |  \\/  |",
+    "| |   | |\\/| |",
+    "| |___| |  | |",
+    "|_____|_|  |_|",
+)
+_CACHE_ART = (
+    "  ____           _          ",
+    " / ___|__ _  ___| |__   ___ ",
+    "| |   / _` |/ __| '_ \\ / _ \\",
+    "| |__| (_| | (__| | | |  __/",
+    " \\____\\__,_|\\___|_| |_|\\___|",
+)
+_RIGHT_TEXT_GAP = "     "
+
+_banner_printed = False
+
+
+def _banner_disabled() -> bool:
+    """Return whether ``LMCACHE_DISABLE_BANNER`` is set to a truthy value."""
+    return os.getenv(DISABLE_BANNER_ENV, "").strip().lower() in ("1", "true", "yes")
+
+
+def _render_banner(colored: bool) -> str:
+    """Render the banner text.
+
+    Args:
+        colored: Whether to wrap the logo in ANSI color escapes.
+
+    Returns:
+        The multi-line banner: the LMCache logo with the version (and
+        commit id when available), website, recipes, and LinkedIn links
+        on its right, and a final line describing the
+        ``LMCACHE_DISABLE_BANNER`` opt-out. A blank line surrounds the
+        banner on each side to set it apart from adjacent log output.
+    """
+    lm_style = _LM_STYLE if colored else ""
+    cache_style = _CACHE_STYLE if colored else ""
+    dim_style = _DIM_STYLE if colored else ""
+    reset = _RESET if colored else ""
+
+    version = f"LMCache v{_LMCACHE_VERSION}"
+    if _LMCACHE_COMMIT:
+        version += f" ({_LMCACHE_COMMIT[:9]})"
+    right_text = {
+        1: version,
+        2: f"Website:  {LMCACHE_WEBSITE}",
+        3: f"Recipes:  {LMCACHE_RECIPES}",
+        4: f"LinkedIn: {LMCACHE_LINKEDIN}",
+    }
+    lines = [""]
+    for row, (lm_part, cache_part) in enumerate(zip(_LM_ART, _CACHE_ART, strict=True)):
+        line = f"{lm_style}{lm_part}{reset} {cache_style}{cache_part}{reset}"
+        if row in right_text:
+            line += _RIGHT_TEXT_GAP + right_text[row]
+        lines.append(line)
+    lines.append(f"{dim_style}Set {DISABLE_BANNER_ENV}=1 to hide this banner.{reset}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def print_banner_once(stream: TextIO) -> None:
+    """Print the LMCache startup banner to ``stream`` at most once.
+
+    The banner shows the LMCache logo, version, and website, followed by
+    a hint describing the ``LMCACHE_DISABLE_BANNER`` opt-out. ANSI colors
+    are used only when ``stream`` is a TTY. Subsequent calls in the same
+    process are no-ops, as are all calls when ``LMCACHE_DISABLE_BANNER``
+    is set to ``1``/``true``/``yes``.
+
+    Args:
+        stream: Destination text stream. Callers should pass
+            ``sys.stderr`` so the banner never interferes with
+            machine-readable stdout output.
+    """
+    global _banner_printed
+    if _banner_printed or _banner_disabled():
+        return
+    _banner_printed = True
+    stream.write(_render_banner(stream.isatty()) + "\n")
+    stream.flush()

lmcache/cli/commands/__init__.py

@@ -1,34 +1,40 @@
 # 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.
+To add a new top-level command, simply create a new module (or sub-package
+with an ``__init__.py``) under this package that defines a concrete
+:class:`BaseCommand` subclass.  It will be discovered and registered
+automatically — no edits to this file are required.
 """
 
 # 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(),
-]
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+
+def _discover_commands() -> list[BaseCommand]:
+    """Scan direct submodules of this package and collect all concrete
+    :class:`BaseCommand` subclasses, returning one instance per class.
+
+    Import errors are intentionally re-raised: a broken CLI command
+    module should fail loudly rather than silently disappear from the
+    CLI.
+    """
+
+    def _raise(module_name: str, exc: Exception) -> None:
+        raise exc
+
+    return [
+        cls()
+        for cls in discover_subclasses(
+            __name__,
+            BaseCommand,  # type: ignore[type-abstract]
+            module_filter=lambda name: name != "base",
+            on_import_error=_raise,
+        )
+    ]
+
+
+ALL_COMMANDS: list[BaseCommand] = _discover_commands()
 
 __all__ = ["ALL_COMMANDS", "BaseCommand"]