lmcache-cli 0.5.1.dev0__py3-none-any.whl → 0.5.1rc3.dev0__py3-none-any.whl

lmcache/__init__.py

@@ -8,6 +8,7 @@ import types
 
 # First Party
 from lmcache.logging import init_logger
+from lmcache.v1.platform.device_ext import DeviceExt
 
 try:
     # First Party
@@ -62,6 +63,17 @@ torch_dev, torch_device_type = _detect_device()
 logger.info(" torch_dev=%s, torch_device_type=%s", torch_dev, torch_device_type)
 
 
+# Attach the DeviceExt instance as ``torch_dev.ext``.  This monkey-patches a
+# standard torch module (e.g. ``torch.cuda``) with a custom attribute that does
+# not exist in the original module.  The ``# type: ignore[attr-defined]`` suppresses
+# the expected mypy/pyright "attr-defined" error from this intentional extension.
+if torch_dev is not None:
+    torch_dev.ext = DeviceExt(torch_device_type)  # type: ignore[attr-defined]
+else:
+    logger.warning("torch_dev is None, skipping DeviceExt initialization.")
+    pass
+
+
 # --------------------------
 # Dynamic backend selection
 # --------------------------

lmcache/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.1.dev0'
-__version_tuple__ = version_tuple = (0, 5, 1, 'dev0')
+__version__ = version = '0.5.1rc3.dev0'
+__version_tuple__ = version_tuple = (0, 5, 1, 'rc3', 'dev0')
 
-__commit_id__ = commit_id = 'g389b9cfcb'
+__commit_id__ = commit_id = 'g979719d7a'

lmcache/banner.py

@@ -8,9 +8,13 @@ only, so tensor-parallel deployments print a single banner). Setting the
 """
 
 # Standard
-from typing import TextIO
+from typing import TYPE_CHECKING
 import os
 
+if TYPE_CHECKING:
+    # Standard
+    from typing import TextIO
+
 try:
     # First Party
     from lmcache import _version
@@ -97,7 +101,7 @@ def _render_banner(colored: bool) -> str:
     return "\n".join(lines)
 
 
-def print_banner_once(stream: TextIO) -> None:
+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

lmcache/cli/commands/bench/engine_bench/interactive/__init__.py

@@ -7,6 +7,7 @@ returns a complete ``argparse.Namespace`` ready for the orchestrator.
 """
 
 # Standard
+from typing import cast
 import argparse
 import sys
 
@@ -20,6 +21,7 @@ from lmcache.cli.commands.bench.engine_bench.interactive.state import (
 from lmcache.cli.commands.bench.engine_bench.interactive.terminal import (
     BOLD,
     CYAN,
+    GO_BACK,
     RESET,
     YELLOW,
     prompt_bool,
@@ -31,18 +33,43 @@ from lmcache.cli.commands.bench.engine_bench.interactive.terminal import (
 __all__ = ["run_interactive"]
 
 
+# Config items whose text input is a URL and accepts port/host shorthand.
+_URL_KEYS = {"engine_url", "lmcache_url"}
+
+
+def _normalize_url(value: str) -> str:
+    """Expand shorthand URL input into a fully-qualified URL.
+
+    A bare port (``8000``) becomes ``http://localhost:8000``; a bare host or
+    ``host:port`` (``localhost:8000``) gains an ``http://`` scheme.  Values
+    that already carry a scheme (``://``) and the empty string are returned
+    unchanged.
+    """
+    value = value.strip()
+    if not value or "://" in value:
+        return value
+    if value.isdigit():
+        return f"http://localhost:{value}"
+    return f"http://{value}"
+
+
 # ---------------------------------------------------------------------------
 # Prompt dispatcher
 # ---------------------------------------------------------------------------
 
 
-def _prompt_for_item(item: ConfigItem) -> object:
-    """Prompt the user for a single config item based on its type."""
+def _prompt_for_item(item: ConfigItem, allow_back: bool) -> object:
+    """Prompt the user for a single config item based on its type.
+
+    Returns the entered value, or :data:`GO_BACK` when ``allow_back`` is True
+    and the user asks to step back to the previous question.
+    """
     if item.input_type == "text":
         return prompt_text(
             item.display_name,
             item.description,
             default=item.default if item.default is not None else "",
+            allow_back=allow_back,
         )
     if item.input_type == "int":
         return prompt_number(
@@ -50,6 +77,7 @@ def _prompt_for_item(item: ConfigItem) -> object:
             item.description,
             default=item.default,
             number_type=int,
+            allow_back=allow_back,
         )
     if item.input_type == "float":
         return prompt_number(
@@ -57,12 +85,14 @@ def _prompt_for_item(item: ConfigItem) -> object:
             item.description,
             default=item.default,
             number_type=float,
+            allow_back=allow_back,
         )
     if item.input_type == "bool":
         return prompt_bool(
             item.display_name,
             item.description,
             default=bool(item.default) if item.default is not None else True,
+            allow_back=allow_back,
         )
     if item.input_type == "choice":
         return prompt_choice(
@@ -70,6 +100,7 @@ def _prompt_for_item(item: ConfigItem) -> object:
             item.description,
             choices=item.choices,
             default=item.default if item.default is not None else "",
+            allow_back=allow_back,
         )
     raise ValueError(f"Unknown input_type {item.input_type!r} for {item.key}")
 
@@ -79,23 +110,20 @@ def _prompt_for_item(item: ConfigItem) -> object:
 # ---------------------------------------------------------------------------
 
 
-def _prompt_gate(section_name: str, detail: str) -> bool:
+def _prompt_gate(section_name: str, detail: str, allow_back: bool) -> object:
     """Ask the user whether to configure a section or skip with defaults.
 
-    Returns True if the user wants to configure.
+    Returns ``"configure"``, ``"use defaults"``, or :data:`GO_BACK`.
     """
-    return (
-        prompt_choice(
-            section_name,
-            f"Would you like to configure {detail}?\n"
-            f"  Defaults will be used if you skip.",
-            choices=[
-                ("use defaults", "Skip, use defaults"),
-                ("configure", "Yes, configure"),
-            ],
-            default="use defaults",
-        )
-        == "configure"
+    return prompt_choice(
+        section_name,
+        f"Would you like to configure {detail}?\n  Defaults will be used if you skip.",
+        choices=[
+            ("use defaults", "Skip, use defaults"),
+            ("configure", "Yes, configure"),
+        ],
+        default="use defaults",
+        allow_back=allow_back,
     )
 
 
@@ -121,10 +149,10 @@ def _print_summary(state: InteractiveState) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _prompt_action() -> str:
-    """Ask the user to start the benchmark or export config.
+def _prompt_action(allow_back: bool) -> object:
+    """Ask the user to start the benchmark, export config, or quit.
 
-    Returns ``"start"`` or ``"export"``.
+    Returns ``"start"``, ``"export"``, ``"quit"``, or :data:`GO_BACK`.
     """
     return prompt_choice(
         "What would you like to do?",
@@ -132,8 +160,10 @@ def _prompt_action() -> str:
         choices=[
             ("start", "Start benchmark"),
             ("export", "Export configuration for later use and exit"),
+            ("quit", "Quit without running"),
         ],
         default="start",
+        allow_back=allow_back,
     )
 
 
@@ -177,10 +207,14 @@ def _resolve_before_export(state: InteractiveState) -> None:
 def _handle_export(state: InteractiveState) -> None:
     """Prompt for filename, resolve values, save JSON, and exit."""
     _resolve_before_export(state)
-    filename = prompt_text(
-        "Export filename",
-        "",
-        default="bench_config.json",
+    # No allow_back here, so the return is always a plain string.
+    filename = cast(
+        str,
+        prompt_text(
+            "Export filename",
+            "",
+            default="bench_config.json",
+        ),
     )
     state.save_json(filename)
     print()
@@ -199,12 +233,116 @@ def _handle_export(state: InteractiveState) -> None:
 # ---------------------------------------------------------------------------
 
 
+# Heading text for each section gate, keyed by section name.
+_GATE_TEXT = {
+    "general": ("General settings", "general settings (model, KV cache volume, etc.)"),
+}
+
+
+def _next_question(
+    state: InteractiveState, gates: dict[str, str]
+) -> ConfigItem | str | None:
+    """Determine the next question to ask.
+
+    Returns a ``ConfigItem`` to prompt for a value, a section name
+    (``"general"`` / ``"workload"``) to prompt the section gate, or None when
+    configuration is complete.  The result is derived purely from current
+    state plus the gate decisions already made, so stepping back (which
+    un-sets the most recent answer) naturally re-presents the question that
+    produced it.
+    """
+    missing = state.get_missing_required()
+    if missing:
+        return missing[0]
+
+    if state.has_unconfigured_general() and "general" not in gates:
+        return "general"
+    if gates.get("general") == "configure":
+        general = state.get_general_items()
+        if general:
+            return general[0]
+
+    workload = [i for i in state.get_workload_items() if not state.is_set(i.key)]
+    if workload and "workload" not in gates:
+        return "workload"
+    if gates.get("workload") == "configure" and workload:
+        return workload[0]
+
+    return None
+
+
+def _gate_text(section: str, state: InteractiveState) -> tuple[str, str]:
+    """Return the ``(section_name, detail)`` heading for a gate prompt."""
+    if section == "workload":
+        return (
+            f"Workload settings ({state.get('workload', 'workload')})",
+            "workload-specific settings",
+        )
+    return _GATE_TEXT[section]
+
+
+def _gather_config(state: InteractiveState) -> bool:
+    """Drive the question loop until the user starts, exports, or quits.
+
+    Walks required items, the general/workload gates, and the summary, while
+    letting the user step back to revise any earlier answer.  Gate decisions
+    are tracked outside ``state`` so they never leak into the exported config.
+
+    Returns True to start the benchmark, False to quit.  Exits the process
+    directly on export.
+    """
+    gates: dict[str, str] = {}
+    # Trail of committed answers, for stepping back.  Item keys are stored as
+    # the key itself; gate decisions as ``"gate:<section>"``.
+    trail: list[str] = []
+
+    def step_back() -> None:
+        marker = trail.pop()
+        if marker.startswith("gate:"):
+            gates.pop(marker[len("gate:") :], None)
+        else:
+            state.unset(marker)
+
+    while True:
+        question = _next_question(state, gates)
+
+        if question is None:
+            _print_summary(state)
+            action = _prompt_action(allow_back=bool(trail))
+            if action is GO_BACK:
+                step_back()
+                continue
+            if action == "export":
+                _handle_export(state)  # exits
+            return action == "start"
+
+        if isinstance(question, ConfigItem):
+            value = _prompt_for_item(question, allow_back=bool(trail))
+            if value is GO_BACK:
+                step_back()
+                continue
+            if question.key in _URL_KEYS and isinstance(value, str):
+                value = _normalize_url(value)
+            state.set(question.key, value)
+            trail.append(question.key)
+        else:
+            name, detail = _gate_text(question, state)
+            choice = _prompt_gate(name, detail, allow_back=bool(trail))
+            if choice is GO_BACK:
+                step_back()
+                continue
+            gates[question] = str(choice)
+            trail.append(f"gate:{question}")
+
+
 def run_interactive(args: argparse.Namespace) -> argparse.Namespace:
     """Run the interactive configuration flow.
 
     Walks the user through missing required items, offers gates for
     general and workload-specific settings, shows a summary, and
-    returns a complete ``argparse.Namespace``.
+    returns a complete ``argparse.Namespace``.  At any prompt the user can
+    step back to the previous question (``<``) or exit (Ctrl-C / Ctrl-D, or
+    the Quit action).
 
     Args:
         args: Partially-populated CLI args (some may be None).
@@ -219,50 +357,19 @@ def run_interactive(args: argparse.Namespace) -> argparse.Namespace:
     print(f"{BOLD}{'═' * 50}{RESET}")
     print(f"{BOLD} lmcache bench engine — Interactive Setup{RESET}")
     print(f"{BOLD}{'═' * 50}{RESET}")
-
-    # ── Phase 1: Required items ───────────────────────────────────────
-    # Walk through missing required items one by one.  Re-evaluate the
-    # list after each prompt because setting one value (e.g., has_lmcache)
-    # can make new items eligible (e.g., lmcache_url) or skip others
-    # (e.g., tokens_per_gb_kvcache).
-    while True:
-        missing = state.get_missing_required()
-        if not missing:
-            break
-        item = missing[0]
-        value = _prompt_for_item(item)
-        state.set(item.key, value)
-
-    # ── Phase 2: General settings gate ────────────────────────────────
-    if state.has_unconfigured_general():
-        if _prompt_gate(
-            "General settings",
-            "general settings (model, KV cache volume, etc.)",
-        ):
-            for item in state.get_general_items():
-                value = _prompt_for_item(item)
-                state.set(item.key, value)
-
-    # ── Phase 3: Workload settings gate (always shown) ────────────────
-    if state.has_workload_items():
-        workload = state.get("workload", "workload")
-        if _prompt_gate(
-            f"Workload settings ({workload})",
-            "workload-specific settings",
-        ):
-            for item in state.get_workload_items():
-                value = _prompt_for_item(item)
-                state.set(item.key, value)
-
-    # Fill all remaining defaults
-    state.fill_defaults()
-
-    # ── Phase 4: Summary + action ─────────────────────────────────────
-    _print_summary(state)
-    action = _prompt_action()
-
-    if action == "export":
-        _handle_export(state)
+    print(f"  {YELLOW}Type < to go back · Ctrl-C to exit{RESET}")
+
+    try:
+        start = _gather_config(state)
+    except (KeyboardInterrupt, EOFError):
+        print()
+        print(f"  {YELLOW}Setup cancelled.{RESET}")
+        sys.exit(0)
+
+    if not start:
+        print()
+        print(f"  {YELLOW}Quit without running.{RESET}")
+        sys.exit(0)
 
     # Carry over output settings from original CLI args
     ns = state.to_namespace()

lmcache/cli/commands/bench/engine_bench/interactive/schema.py

@@ -90,7 +90,8 @@ ALL_ITEMS: list[ConfigItem] = [
         key="engine_url",
         display_name="Engine URL",
         description=(
-            "URL of the inference engine. "
+            "URL of the inference engine. Enter just a port (e.g. 8000) to "
+            "use http://localhost:8000. "
             "Set OPENAI_API_KEY env var if authentication is needed."
         ),
         input_type="text",
@@ -135,7 +136,10 @@ ALL_ITEMS: list[ConfigItem] = [
     ConfigItem(
         key="lmcache_url",
         display_name="LMCache Server URL",
-        description="URL of the running LMCache HTTP server.",
+        description=(
+            "URL of the running LMCache HTTP server. Enter just a port "
+            "(e.g. 8080) to use http://localhost:8080."
+        ),
         input_type="text",
         default="http://localhost:8080",
         required=False,

lmcache/cli/commands/bench/engine_bench/interactive/state.py

@@ -74,6 +74,10 @@ class InteractiveState:
     def set(self, key: str, value: Any) -> None:
         self._values[key] = value
 
+    def unset(self, key: str) -> None:
+        """Remove a key so it counts as unset again (used when stepping back)."""
+        self._values.pop(key, None)
+
     @property
     def values(self) -> dict[str, Any]:
         return dict(self._values)

lmcache/cli/commands/bench/engine_bench/interactive/terminal.py

@@ -7,11 +7,28 @@ Provides simple prompt functions for collecting user input:
 - ``prompt_number`` — numeric input with type validation
 - ``prompt_bool`` — Y/N confirmation
 - ``prompt_choice`` — arrow-key selection (falls back to numbered list on non-TTY)
+
+Every prompt accepts ``allow_back``.  When enabled, the user steps back to the
+previous question by typing ``<`` — in every prompt, typed or arrow-key — in
+which case the prompt returns the :data:`GO_BACK` sentinel instead of a value.
 """
 
 # Standard
 import sys
 
+
+class _GoBack:
+    """Sentinel type returned by prompts when the user asks to step back."""
+
+
+# Returned by any prompt (when ``allow_back=True``) to mean "go to the
+# previous question".  Compare with ``is`` — there is only one instance.
+GO_BACK = _GoBack()
+
+# Token the user types to go back, in any text/number/bool prompt and in the
+# non-TTY choice fallback.
+BACK_TOKEN = "<"
+
 # ---------------------------------------------------------------------------
 # ANSI helpers
 # ---------------------------------------------------------------------------
@@ -30,6 +47,11 @@ def _is_tty() -> bool:
     return hasattr(sys.stdin, "fileno") and sys.stdin.isatty()
 
 
+def _print_back_hint() -> None:
+    """Print the dim 'type < to go back' hint used by typed prompts."""
+    print(f"  {DIM}(type {BACK_TOKEN} to go back){RESET}")
+
+
 # ---------------------------------------------------------------------------
 # prompt_text
 # ---------------------------------------------------------------------------
@@ -39,26 +61,33 @@ def prompt_text(
     label: str,
     description: str = "",
     default: str = "",
-) -> str:
+    allow_back: bool = False,
+) -> str | _GoBack:
     """Prompt for free-form text input.
 
     Args:
         label: The config item name shown as a heading.
         description: One-line explanation shown below the label.
         default: Default value; shown in brackets, returned on empty Enter.
+        allow_back: If True, typing ``<`` returns :data:`GO_BACK`.
 
     Returns:
-        The user's input, or the default if they pressed Enter.
+        The user's input, the default if they pressed Enter, or
+        :data:`GO_BACK` if they asked to step back.
     """
     print()
     print(f"{BOLD}{label}{RESET}")
     if description:
         print(f"  {description}")
+    if allow_back:
+        _print_back_hint()
     if default:
         prompt = f"  {DIM}[default: {default}]{RESET} {GREEN}>{RESET} "
     else:
         prompt = f"  {GREEN}>{RESET} "
     value = input(prompt).strip()
+    if allow_back and value == BACK_TOKEN:
+        return GO_BACK
     return value if value else default
 
 
@@ -72,7 +101,8 @@ def prompt_number(
     description: str = "",
     default: float | int | None = None,
     number_type: type = int,
-) -> float | int:
+    allow_back: bool = False,
+) -> float | int | _GoBack:
     """Prompt for a numeric value with validation.
 
     Args:
@@ -80,14 +110,17 @@ def prompt_number(
         description: One-line explanation.
         default: Default value; returned on empty Enter.  None means required.
         number_type: ``int`` or ``float``.
+        allow_back: If True, typing ``<`` returns :data:`GO_BACK`.
 
     Returns:
-        The parsed number.
+        The parsed number, or :data:`GO_BACK` if the user asked to step back.
     """
     print()
     print(f"{BOLD}{label}{RESET}")
     if description:
         print(f"  {description}")
+    if allow_back:
+        _print_back_hint()
 
     while True:
         if default is not None:
@@ -95,6 +128,8 @@ def prompt_number(
         else:
             prompt = f"  {GREEN}>{RESET} "
         raw = input(prompt).strip()
+        if allow_back and raw == BACK_TOKEN:
+            return GO_BACK
         if not raw and default is not None:
             return default
         try:
@@ -113,7 +148,8 @@ def prompt_bool(
     label: str,
     description: str = "",
     default: bool = True,
-) -> bool:
+    allow_back: bool = False,
+) -> bool | _GoBack:
     """Prompt for a yes/no confirmation.
 
     Shows ``[Y/n]`` or ``[y/N]`` depending on the default.
@@ -123,18 +159,24 @@ def prompt_bool(
         label: The config item name.
         description: One-line explanation.
         default: Default value when user presses Enter.
+        allow_back: If True, typing ``<`` returns :data:`GO_BACK`.
 
     Returns:
-        True for yes, False for no.
+        True for yes, False for no, or :data:`GO_BACK` if the user asked to
+        step back.
     """
     print()
     print(f"{BOLD}{label}{RESET}")
     if description:
         print(f"  {description}")
+    if allow_back:
+        _print_back_hint()
 
     hint = "[default: Y] (Y/n)" if default else "[default: N] (y/N)"
     while True:
         raw = input(f"  {DIM}{hint}{RESET} {GREEN}>{RESET} ").strip().lower()
+        if allow_back and raw == BACK_TOKEN:
+            return GO_BACK
         if not raw:
             return default
         if raw in ("y", "yes"):
@@ -164,6 +206,12 @@ def _read_key() -> str:
     try:
         tty.setraw(fd)
         ch = sys.stdin.read(1)
+        # Raw mode disables signal generation, so translate Ctrl-C / Ctrl-D
+        # into the usual exceptions the caller already expects.
+        if ch == "\x03":
+            raise KeyboardInterrupt
+        if ch == "\x04":
+            raise EOFError
         if ch == "\r" or ch == "\n":
             return "enter"
         if ch == "\x1b":
@@ -201,7 +249,8 @@ def prompt_choice(
     description: str = "",
     choices: list[tuple[str, str]] = [],  # noqa: B006
     default: str = "",
-) -> str:
+    allow_back: bool = False,
+) -> str | _GoBack:
     """Prompt user to select from a list using arrow keys.
 
     Each choice is a ``(value, description)`` tuple.  The description is
@@ -214,9 +263,11 @@ def prompt_choice(
         description: One-line explanation.
         choices: List of ``(value, one_line_description)`` tuples.
         default: Pre-selected value.  Defaults to the first choice.
+        allow_back: If True, pressing ``<`` returns :data:`GO_BACK`.
 
     Returns:
-        The selected value string.
+        The selected value string, or :data:`GO_BACK` if the user asked to
+        step back.
     """
     if not choices:
         raise ValueError("choices must not be empty")
@@ -235,9 +286,11 @@ def prompt_choice(
 
     # Non-TTY fallback: numbered list
     if not _is_tty():
-        return _prompt_choice_fallback(choices, selected)
+        return _prompt_choice_fallback(choices, selected, allow_back)
 
-    print(f"  {DIM}Use ↑↓ to navigate, Enter to select.{RESET}")
+    nav = "Use ↑↓ to navigate, Enter to select"
+    nav += f", {BACK_TOKEN} to go back." if allow_back else "."
+    print(f"  {DIM}{nav}{RESET}")
     print()
 
     # Initial render
@@ -251,14 +304,14 @@ def prompt_choice(
             selected = (selected - 1) % len(choices)
         elif key == "down":
             selected = (selected + 1) % len(choices)
-        elif key == "enter":
+        elif key == "enter" or (key == BACK_TOKEN and allow_back):
             # Clear and re-render final state
             num_lines = len(choices)
             sys.stdout.write(f"\r{CURSOR_UP * num_lines}")
             lines = _render_choices(choices, selected)
             for line in lines:
                 print(f"{CLEAR_LINE}{line}")
-            return choices[selected][0]
+            return GO_BACK if key == BACK_TOKEN else choices[selected][0]
         else:
             continue
 
@@ -273,13 +326,18 @@ def prompt_choice(
 def _prompt_choice_fallback(
     choices: list[tuple[str, str]],
     default_index: int,
-) -> str:
+    allow_back: bool = False,
+) -> str | _GoBack:
     """Numbered fallback for non-TTY environments."""
     for i, (val, desc) in enumerate(choices):
         marker = "*" if i == default_index else " "
         print(f"  {marker} {i + 1}) {val}  — {desc}")
+    if allow_back:
+        _print_back_hint()
     while True:
         raw = input(f"  [default: {default_index + 1}] {GREEN}>{RESET} ").strip()
+        if allow_back and raw == BACK_TOKEN:
+            return GO_BACK
         if not raw:
             return choices[default_index][0]
         try: