flexsds 0.2.0__py3-none-any.whl

flexsds/__init__.py

@@ -0,0 +1,4 @@
+"""FlexSDS: Flexible Speculative Decoding Serving Engine for LLMs."""
+
+__version__ = "0.2.0"
+__author__ = "Can Duc Khoi, Bui Duc Dai & Nguyen The Duong"

flexsds/cli/__init__.py

@@ -0,0 +1 @@
+"""FlexSDS CLI module."""

flexsds/cli/banner.py

@@ -0,0 +1,84 @@
+"""FlexSDS branding banner module with PTIT logo in ANSI TrueColor."""
+from __future__ import annotations
+
+import sys
+from typing import Optional
+try:
+    from flexsds.cli.output import ascii_text, print_output, supports_truecolor, supports_unicode
+    from flexsds.core.hardware import HardwareInfo, detect_hardware
+except ModuleNotFoundError:
+    from src.flexsds.cli.output import ascii_text, print_output, supports_truecolor, supports_unicode
+    from src.flexsds.core.hardware import HardwareInfo, detect_hardware
+
+# Pre-compiled ANSI grayscale half-blocks for the official PTIT logo (26 cols x 12 rows)
+# Zero-dependency, sub-millisecond monochrome rendering without PIL at runtime.
+PTIT_LOGO_ANSI = [
+    "            \033[38;2;181;181;181m▄\033[0m\033[38;2;112;112;112m▄\033[0m\033[38;2;185;185;185;48;2;119;119;119m▀\033[0m\033[38;2;128;128;128;48;2;154;154;154m▀\033[0m\033[38;2;95;95;95;48;2;176;176;176m▀\033[0m\033[38;2;81;81;81;48;2;175;175;175m▀\033[0m\033[38;2;83;83;83;48;2;145;145;145m▀\033[0m\033[38;2;103;103;103;48;2;95;95;95m▀\033[0m\033[38;2;140;140;140;48;2;72;72;72m▀\033[0m\033[38;2;214;214;214;48;2;87;87;87m▀\033[0m\033[38;2;196;196;196m▄\033[0m   ",
+    "         \033[38;2;170;170;170m▄\033[0m\033[38;2;202;202;202;48;2;165;165;165m▀\033[0m\033[38;2;139;139;139;48;2;222;222;222m▀\033[0m\033[38;2;150;150;150m▀\033[0m\033[38;2;221;221;221m▀\033[0m      \033[38;2;149;149;149m▀\033[0m\033[38;2;74;74;74;48;2;138;138;138m▀\033[0m\033[38;2;101;101;101;48;2;74;74;74m▀\033[0m\033[38;2;216;216;216m▄\033[0m  ",
+    "      \033[38;2;211;211;211m▄\033[0m\033[38;2;215;215;215;48;2;152;152;152m▀\033[0m\033[38;2;169;169;169m▀\033[0m\033[38;2;215;215;215m▀\033[0m           \033[38;2;222;222;222m▀\033[0m\033[38;2;76;76;76;48;2;99;99;99m▀\033[0m\033[38;2;206;206;206;48;2;214;214;214m▀\033[0m  ",
+    "     \033[38;2;221;221;221;48;2;108;108;108m▀\033[0m\033[38;2;125;125;125;48;2;217;217;217m▀\033[0m               \033[38;2;120;120;120;48;2;145;145;145m▀\033[0m   ",
+    "   \033[38;2;177;177;177m▄\033[0m\033[38;2;124;124;124;48;2;87;87;87m▀\033[0m\033[38;2;155;155;155m▀\033[0m             \033[38;2;231;231;231m▄\033[0m \033[38;2;208;208;208;48;2;187;187;187m▀\033[0m\033[38;2;187;187;187m▀\033[0m   ",
+    "  \033[38;2;160;160;160m▄\033[0m\033[38;2;80;80;80;48;2;71;71;71m▀\033[0m\033[38;2;160;160;160;48;2;227;227;227m▀\033[0m \033[38;2;185;185;185m▄\033[0m\033[38;2;181;181;181m▄\033[0m\033[38;2;178;178;178m▄\033[0m\033[38;2;212;212;212m▄\033[0m \033[38;2;183;183;183m▄\033[0m\033[38;2;185;185;185m▄\033[0m\033[38;2;193;193;193m▄\033[0m\033[38;2;176;176;176m▄\033[0m\033[38;2;210;210;210m▄\033[0m\033[38;2;232;232;232m▄\033[0m\033[38;2;230;230;230m▄\033[0m\033[38;2;218;218;218;48;2;181;181;181m▀\033[0m\033[38;2;219;219;219;48;2;207;207;207m▀\033[0m\033[38;2;229;229;229m▄\033[0m\033[38;2;227;227;227;48;2;170;170;170m▀\033[0m\033[38;2;173;173;173m▄\033[0m\033[38;2;181;181;181m▄\033[0m\033[38;2;166;166;166m▄\033[0m\033[38;2;198;198;198m▄\033[0m",
+    " \033[38;2;209;209;209m▄\033[0m\033[38;2;98;98;98;48;2;71;71;71m▀\033[0m\033[38;2;100;100;100;48;2;132;132;132m▀\033[0m \033[38;2;180;180;180;48;2;181;181;181m▀\033[0m\033[38;2;77;77;77;48;2;95;95;95m▀\033[0m\033[38;2;179;179;179;48;2;225;225;225m▀\033[0m\033[38;2;170;170;170;48;2;218;218;218m▀\033[0m\033[38;2;94;94;94;48;2;92;92;92m▀\033[0m\033[38;2;155;155;155;48;2;145;145;145m▀\033[0m\033[38;2;173;173;173m▀\033[0m\033[38;2;129;129;129;48;2;196;196;196m▀\033[0m\033[38;2;90;90;90;48;2;111;111;111m▀\033[0m\033[38;2;161;161;161m▀\033[0m\033[38;2;206;206;206;48;2;246;246;246m▀\033[0m\033[38;2;218;218;218;48;2;210;210;210m▀\033[0m\033[38;2;173;173;173;48;2;185;185;185m▀\033[0m\033[38;2;194;194;194;48;2;205;205;205m▀\033[0m\033[38;2;232;232;232m▀\033[0m \033[38;2;177;177;177m▀\033[0m\033[38;2;137;137;137;48;2;200;200;200m▀\033[0m\033[38;2;86;86;86;48;2;107;107;107m▀\033[0m\033[38;2;172;172;172m▀\033[0m\033[38;2;202;202;202m▀\033[0m",
+    " \033[38;2;165;165;165;48;2;138;138;138m▀\033[0m\033[38;2;66;66;66;48;2;68;68;68m▀\033[0m\033[38;2;149;149;149;48;2;149;149;149m▀\033[0m \033[38;2;183;183;183;48;2;173;173;173m▀\033[0m\033[38;2;86;86;86;48;2;86;86;86m▀\033[0m\033[38;2;143;143;143m▀\033[0m\033[38;2;138;138;138m▀\033[0m\033[38;2;168;168;168m▀\033[0m  \033[38;2;188;188;188;48;2;184;184;184m▀\033[0m\033[38;2;110;110;110;48;2;95;95;95m▀\033[0m \033[38;2;221;221;221m▄\033[0m\033[38;2;222;222;222;48;2;107;107;107m▀\033[0m\033[38;2;144;144;144;48;2;129;129;129m▀\033[0m\033[38;2;133;133;133;48;2;92;92;92m▀\033[0m   \033[38;2;190;190;190;48;2;186;186;186m▀\033[0m\033[38;2;106;106;106;48;2;92;92;92m▀\033[0m  ",
+    " \033[38;2;126;126;126;48;2;135;135;135m▀\033[0m\033[38;2;72;72;72;48;2;78;78;78m▀\033[0m\033[38;2;131;131;131;48;2;97;97;97m▀\033[0m \033[38;2;217;217;217m▀\033[0m\033[38;2;178;178;178m▀\033[0m     \033[38;2;221;221;221m▀\033[0m\033[38;2;182;182;182;48;2;157;157;157m▀\033[0m\033[38;2;198;198;198;48;2;68;68;68m▀\033[0m\033[38;2;81;81;81;48;2;101;101;101m▀\033[0m\033[38;2;106;106;106;48;2;224;224;224m▀\033[0m\033[38;2;197;197;197m▀\033[0m\033[38;2;179;179;179m▀\033[0m   \033[38;2;223;223;223m▀\033[0m\033[38;2;181;181;181m▀\033[0m  ",
+    " \033[38;2;193;193;193m▀\033[0m\033[38;2;74;74;74;48;2;165;165;165m▀\033[0m\033[38;2;77;77;77;48;2;96;96;96m▀\033[0m\033[38;2;145;145;145;48;2;86;86;86m▀\033[0m\033[38;2;152;152;152m▄\033[0m  \033[38;2;227;227;227m▄\033[0m\033[38;2;166;166;166m▄\033[0m\033[38;2;93;93;93m▄\033[0m\033[38;2;175;175;175;48;2;69;69;69m▀\033[0m\033[38;2;87;87;87;48;2;121;121;121m▀\033[0m\033[38;2;68;68;68;48;2;205;205;205m▀\033[0m\033[38;2;142;142;142m▀\033[0m           ",
+    "   \033[38;2;195;195;195m▀\033[0m\033[38;2;148;148;148;48;2;209;209;209m▀\033[0m\033[38;2;124;124;124;48;2;179;179;179m▀\033[0m\033[38;2;130;130;130;48;2;160;160;160m▀\033[0m\033[38;2;117;117;117;48;2;164;164;164m▀\033[0m\033[38;2;88;88;88;48;2;193;193;193m▀\033[0m\033[38;2;94;94;94;48;2;226;226;226m▀\033[0m\033[38;2;147;147;147m▀\033[0m\033[38;2;218;218;218m▀\033[0m              ",
+    "\033[38;2;125;125;125;48;2;141;141;141m▀\033[0m\033[38;2;118;118;118;48;2;136;136;136m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m\033[38;2;120;120;120;48;2;138;138;138m▀\033[0m\033[38;2;125;125;125;48;2;137;137;137m▀\033[0m\033[38;2;130;130;130;48;2;136;136;136m▀\033[0m\033[38;2;133;133;133;48;2;136;136;136m▀\033[0m\033[38;2;132;132;132;48;2;137;137;137m▀\033[0m\033[38;2;128;128;128;48;2;138;138;138m▀\033[0m\033[38;2;122;122;122;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;141;141;141m▀\033[0m\033[38;2;113;113;113;48;2;136;136;136m▀\033[0m\033[38;2;148;148;148;48;2;141;141;141m▀\033[0m\033[38;2;149;149;149;48;2;144;144;144m▀\033[0m\033[38;2;114;114;114;48;2;134;134;134m▀\033[0m\033[38;2;118;118;118;48;2;143;143;143m▀\033[0m\033[38;2;118;118;118;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;139;139;139m▀\033[0m\033[38;2;119;119;119;48;2;139;139;139m▀\033[0m\033[38;2;119;119;119;48;2;138;138;138m▀\033[0m\033[38;2;119;119;119;48;2;138;138;138m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m",
+]
+
+def render_banner(hw_info: Optional[HardwareInfo] = None) -> str:
+    """Builds and returns the complete side-by-side FlexSDS banner."""
+    if hw_info is None:
+        hw_info = detect_hardware()
+
+    gpu_str = hw_info.summary()
+
+    info_lines = [
+        "\033[1;37m  ███████╗██╗     ███████╗██╗  ██╗███████╗██████╗ ███████╗\033[0m",
+        "\033[1;37m  ██╔════╝██║     ██╔════╝╚██╗██╔╝██╔════╝██╔══██╗██╔════╝\033[0m",
+        "\033[1;37m  █████╗  ██║     █████╗   ╚███╔╝ ███████╗██║  ██║███████╗\033[0m",
+        "\033[1;37m  ██╔══╝  ██║     ██╔══╝   ██╔██╗ ╚════██║██║  ██║╚════██║\033[0m",
+        "\033[1;37m  ██║     ███████╗███████╗██╔╝ ██╗███████║██████╔╝███████║\033[0m",
+        "",
+        "  \033[1;37mFlexSDS\033[0m \033[90m· Speculative Decoding Serving Engine · v0.2.0-alpha\033[0m",
+        "  \033[90mNhóm đồ án D22\033[0m",
+        "  \033[90mHọc viện Công nghệ Bưu chính Viễn thông (PTIT)\033[0m",
+        "",
+        f"  \033[90m•\033[0m \033[37mHardware\033[0m    : \033[90m{gpu_str}\033[0m",
+        "  \033[90m•\033[0m \033[37mEngine\033[0m      : \033[90mHardwareAdaptive v0.2\033[0m",
+        "  \033[90m•\033[0m \033[37mBackends\033[0m    : \033[90mModal / Colab / Local vLLM\033[0m",
+    ]
+
+    max_rows = max(len(PTIT_LOGO_ANSI), len(info_lines))
+    col_logo = list(PTIT_LOGO_ANSI) + [" " * 26] * (max_rows - len(PTIT_LOGO_ANSI))
+    col_info = list(info_lines) + [""] * (max_rows - len(info_lines))
+
+    output = []
+    for l, r in zip(col_logo, col_info):
+        output.append(f" {l}  {r}")
+    return "\n".join(output)
+
+
+def render_ascii_banner(hw_info: HardwareInfo) -> str:
+    """Compact branding/status fallback; hardware logic remains in HardwareInfo."""
+    return ascii_text(
+        "FlexSDS | Speculative Decoding Serving Engine | v0.2.0-alpha\n"
+        "PTIT | Hoc vien Cong nghe Buu chinh Vien thong | Nhom do an D22\n"
+        f"Hardware: {hw_info.summary()}\n"
+        "Engine: TreeAdaptive v0.2\n"
+        "Backends: Modal / Colab / Local vLLM"
+    )
+
+
+def print_banner(hw_info: Optional[HardwareInfo] = None) -> None:
+    """Preserve rich branding on capable terminals; otherwise use plain ASCII."""
+    if hw_info is None:
+        hw_info = detect_hardware()
+    fallback = render_ascii_banner(hw_info)
+    rich = supports_unicode(sys.stdout) and supports_truecolor(sys.stdout)
+    print_output(render_banner(hw_info) if rich else fallback, fallback=fallback)
+
+
+if __name__ == "__main__":
+    print_banner()

flexsds/cli/main.py

@@ -0,0 +1,330 @@
+"""FlexSDS CLI main dispatcher module."""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional
+
+try:
+    from flexsds.cli.output import print_output as print
+    from flexsds import __version__
+    from flexsds.cli.banner import print_banner
+    from flexsds.cli.wizard import run_interactive_wizard
+    from flexsds.core.hardware import detect_hardware, HardwareInfo
+    from flexsds.core.compatibility import (
+        check_compatibility,
+        evaluate_serving_preflight,
+        ServingBlockedError,
+    )
+    from flexsds.core.cost_model import (
+        FlexCostModel,
+        load_profile_for_hardware,
+        run_hardware_micro_benchmark,
+    )
+    from flexsds.core.credentials import CredentialsManager
+    from flexsds.client.chat import run_interactive_chat
+    from flexsds.client.monitor import run_live_monitor
+    from flexsds.cli.task_runner import TaskRunner
+    from flexsds.server.local_runner import LocalServingRunner, finish_launch
+    from flexsds.server.modal_runner import ModalServingRunner
+except ModuleNotFoundError:
+    from src.flexsds.cli.output import print_output as print
+    from src.flexsds import __version__
+    from src.flexsds.cli.banner import print_banner
+    from src.flexsds.cli.wizard import run_interactive_wizard
+    from src.flexsds.core.hardware import detect_hardware, HardwareInfo
+    from src.flexsds.core.compatibility import (
+        check_compatibility,
+        evaluate_serving_preflight,
+        ServingBlockedError,
+    )
+    from src.flexsds.core.cost_model import (
+        FlexCostModel,
+        load_profile_for_hardware,
+        run_hardware_micro_benchmark,
+    )
+    from src.flexsds.core.credentials import CredentialsManager
+    from src.flexsds.client.chat import run_interactive_chat
+    from src.flexsds.client.monitor import run_live_monitor
+    from src.flexsds.cli.task_runner import TaskRunner
+    from src.flexsds.server.local_runner import LocalServingRunner, finish_launch
+    from src.flexsds.server.modal_runner import ModalServingRunner
+
+
+def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="flexsds",
+        description="FlexSDS: Flexible Speculative Decoding Serving Engine for LLMs",
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"flexsds {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # Command: detect
+    subparsers.add_parser("detect", help="Detect and display hardware / GPU specs")
+
+    # Command: profile
+    profile_parser = subparsers.add_parser("profile", help="Load hardware cost profile for current GPU")
+    profile_parser.add_argument(
+        "--benchmark",
+        action="store_true",
+        help="Run micro-benchmark to measure and save profile",
+    )
+    profile_parser.add_argument(
+        "--target",
+        type=str,
+        default="Qwen/Qwen2.5-7B-Instruct-AWQ",
+        help="Target model identifier",
+    )
+    profile_parser.add_argument(
+        "--draft",
+        type=str,
+        default="duckhoi/qwen2.5-7b-eagle3.1-speculator",
+        help="Draft model or speculator head identifier",
+    )
+    profile_parser.add_argument(
+        "--model",
+        type=str,
+        default=None,
+        help="Model identifier override for benchmarking",
+    )
+
+    # Command: stop
+    subparsers.add_parser("stop", help="Stop running local FlexSDS server")
+
+    # Command: auth
+    auth_parser = subparsers.add_parser("auth", help="Manage secure credentials outside repository")
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_action", help="Auth action to perform")
+    
+    # auth login
+    auth_login_parser = auth_subparsers.add_parser("login", help="Save API key / token securely")
+    auth_login_parser.add_argument("--provider", choices=["modal", "huggingface", "cloudflare"], default="modal", help="Target service provider")
+    auth_login_parser.add_argument("--key", type=str, default=None, help="Specific credential key name")
+    auth_login_parser.add_argument("--token", type=str, default=None, help="Token value (prompted securely if omitted)")
+
+    # auth status
+    auth_subparsers.add_parser("status", help="Show masked status of saved credentials")
+
+    # auth logout
+    auth_logout_parser = auth_subparsers.add_parser("logout", help="Delete saved credentials")
+    auth_logout_parser.add_argument("--provider", type=str, default=None, help="Target service provider to remove")
+
+    # Command: serve
+    serve_parser = subparsers.add_parser("serve", help="Launch speculative serving server")
+    serve_parser.add_argument("--target", type=str, help="Target model identifier")
+    serve_parser.add_argument("--draft", type=str, help="Draft model or speculator head identifier")
+    serve_parser.add_argument(
+        "--backend", choices=["modal", "local", "colab"], default="modal", help="Serving backend platform"
+    )
+    serve_parser.add_argument("--gpu", choices=["L4", "T4", "A10G"], default="L4", help="Remote GPU memory budget and Modal allocation")
+    serve_parser.add_argument(
+        "--port", type=int, default=8000, help="API server port"
+    )
+    serve_parser.add_argument(
+        "--background", action="store_true", help="Run local server as background daemon"
+    )
+    serve_parser.add_argument(
+        "--deploy", action="store_true", help="Deploy persistently on Modal Cloud"
+    )
+    serve_parser.add_argument(
+        "--no-adaptive", action="store_true", help="Disable HardwareAdaptive optimization engine"
+    )
+    serve_parser.add_argument(
+        "--allow-fallback", action="store_true", help="Allow running with conservative analytical fallback if exact GPU profile is missing"
+    )
+    serve_parser.add_argument(
+        "--dry-run", action="store_true", help="Print execution command without launching"
+    )
+
+    # Command: chat
+    chat_parser = subparsers.add_parser("chat", help="Start interactive streaming chat with served model")
+    chat_parser.add_argument("--endpoint", type=str, default="http://localhost:8000/v1", help="API base URL")
+    chat_parser.add_argument("--model", type=str, default=None, help="Served model name override")
+    chat_parser.add_argument("--temperature", type=float, default=0.0, help="Sampling temperature")
+
+    # Command: monitor
+    monitor_parser = subparsers.add_parser("monitor", help="Live telemetry monitor for speculative decoding traces")
+    monitor_parser.add_argument("--trace-file", type=str, default="telemetry/serving_trace.jsonl", help="Path to JSONL telemetry trace")
+    monitor_parser.add_argument("--refresh-rate", type=float, default=1.0, help="Telemetry poll interval in seconds")
+
+    return parser.parse_args(argv)
+
+
+def get_serving_cost_profile(
+    hw_info: HardwareInfo,
+    allow_fallback: bool = False,
+    custom_profile_path: Optional[str] = None,
+) -> tuple[Optional[FlexCostModel], str]:
+    """Tải hồ sơ chi phí phần cứng phục vụ cho lệnh serve với cơ chế chặn sớm (fail-fast).
+
+    Nếu allow_fallback=False và không tìm thấy hồ sơ chính xác cho GPU hiện tại,
+    trả về (None, "") để kích hoạt xử lý chặn sớm an toàn.
+    Nếu allow_fallback=True, cho phép nạp hồ sơ suy diễn dè dặt phân tích an toàn.
+    """
+    return load_profile_for_hardware(
+        hw_info,
+        custom_profile_path=custom_profile_path,
+        strict=not allow_fallback,
+    )
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    """Main entry point for FlexSDS command-line interface."""
+    args = parse_args(argv)
+    if args.command == "serve" and not 1 <= args.port <= 65535:
+        print("Invalid port: expected 1..65535")
+        return 2
+    if args.command == "monitor" and args.refresh_rate <= 0:
+        print("Refresh rate must be positive")
+        return 2
+    hw_info = detect_hardware()
+
+    if args.command == "stop":
+        local_runner = LocalServingRunner()
+        local_stopped = local_runner.stop()
+        if local_stopped:
+            print("\033[32m✔ Local vLLM server process stopped successfully.\033[0m")
+        else:
+            print("\033[90mNo active local server process found.\033[0m")
+        return 0
+
+    if args.command == "auth":
+        cred_mgr = CredentialsManager()
+        if args.auth_action == "status":
+            masked = cred_mgr.get_all_masked()
+            print("\n\033[1;37mFlexSDS Secure Credentials (~/.flexsds/credentials):\033[0m")
+            if not masked:
+                print("  \033[90m(No credentials saved. Run 'flexsds auth login' to add.)\033[0m")
+            for prov, keys in masked.items():
+                print(f"  \033[32m✔ {prov}:\033[0m")
+                for k, v in keys.items():
+                    print(f"      {k}: {v}")
+            return 0
+        elif args.auth_action == "logout":
+            target_prov = getattr(args, "provider", None)
+            if target_prov:
+                deleted = cred_mgr.delete_credential(target_prov)
+                if deleted:
+                    print(f"\033[32m✔ Removed credentials for provider: {target_prov}\033[0m")
+                else:
+                    print(f"\033[90mNo credentials found for provider: {target_prov}\033[0m")
+            else:
+                for prov in list(cred_mgr.get_all_masked().keys()):
+                    cred_mgr.delete_credential(prov)
+                print("\033[32m✔ Removed all stored credentials.\033[0m")
+            return 0
+        elif args.auth_action == "login":
+            import getpass
+            prov = args.provider
+            key_name = args.key or ("HF_TOKEN" if prov == "huggingface" else ("MODAL_TOKEN_ID" if prov == "modal" else "TOKEN"))
+            val = args.token or getpass.getpass(f"Enter {key_name} for {prov}: ")
+            if val:
+                cred_mgr.set_credential(prov, key_name, val.strip())
+                print(f"\033[32m✔ Securely saved {key_name} for {prov} (POSIX mode 0600; Windows uses filesystem ACLs).\033[0m")
+            return 0
+        return 0
+
+    # Display banner on interactive startup or regular commands
+    print_banner(hw_info)
+
+    if args.command == "detect":
+        print(f"\n\033[1;32m✔ Hardware: {hw_info.summary()}\033[0m")
+        return 0
+
+    if args.command == "profile":
+        if getattr(args, "benchmark", False):
+            target_model = args.model or args.target
+            draft_model = args.draft
+            cost_model, saved_path = run_hardware_micro_benchmark(
+                hw_info=hw_info,
+                target_model=target_model,
+                draft_model=draft_model,
+            )
+            print(f"\n\033[1;32m✔ Calibrated & saved new hardware profile: {saved_path}\033[0m")
+            return 0
+
+        _, profile_name = load_profile_for_hardware(hw_info)
+        print(f"\n\033[1;32m✔ Linked hardware profile: {profile_name}\033[0m")
+        return 0
+
+    if args.command == "chat":
+        return run_interactive_chat(
+            endpoint=args.endpoint,
+            model=args.model,
+            temperature=args.temperature,
+        )
+
+    if args.command == "monitor":
+        return run_live_monitor(
+            trace_file=args.trace_file,
+            refresh_rate=args.refresh_rate,
+        )
+
+    if args.command == "serve":
+        cost_model, profile_name = get_serving_cost_profile(
+            hw_info, allow_fallback=getattr(args, "allow_fallback", False)
+        )
+        if cost_model is None:
+            print(
+                f"\n\033[1;31m✖ [Lỗi phần cứng] Chưa có hồ sơ độ trễ cho GPU '{hw_info.device_name} ({hw_info.sm_architecture})'. "
+                f"Vui lòng chạy lệnh đo đạc: flexsds profile --benchmark (hoặc thêm cờ '--allow-fallback').\033[0m"
+            )
+            return 1
+
+        if profile_name == "conservative_analytical_fallback":
+            print(
+                f"  \033[1;33m⚠ [Cảnh báo phần cứng] Sử dụng hồ sơ suy diễn dè dặt ({profile_name} / Conservative Fallback).\033[0m"
+            )
+
+        if args.target and args.draft:
+            target_model = args.target
+            draft_model = args.draft
+
+            preflight = evaluate_serving_preflight(target_model, draft_model, hw_info,
+                                                   args.backend, getattr(args, "gpu", "L4"))
+            print(preflight.report.summary())
+            if not preflight.is_safe:
+                print("Launch blocked: " + "; ".join(preflight.reasons))
+            if args.backend != "local":
+                print(f"Remote {getattr(args, 'gpu', 'L4')} memory budget is estimated, not measured free VRAM.")
+            cfg = {"serving": {
+                "target_model": target_model, "draft_model": draft_model,
+                "draft_method": preflight.report.draft_method,
+                "use_heterogeneous_vocab": preflight.report.use_heterogeneous_vocab,
+                "port": args.port, "target_gpu": getattr(args, "gpu", "L4"),
+                "enable_adaptive": not args.no_adaptive,
+            }}
+            if args.backend == "colab":
+                print("Colab guidance only: no server or endpoint was created; supplied models are not forwarded to the notebook.")
+                print("Open notebooks/flexsds_colab_server.ipynb and configure the exact models on that runtime.")
+                return 0
+            if not args.dry_run and not preflight.is_safe:
+                return 2
+            if args.dry_run:
+                print("Preview only; not a readiness check.")
+                if args.backend == "local":
+                    LocalServingRunner().launch(cfg, port=args.port, background=args.background, dry_run=True)
+                else:
+                    ModalServingRunner().launch(cfg, deploy=args.deploy, dry_run=True)
+                return 0
+            tasks = TaskRunner()
+            task = tasks.add_task(f"Start {args.backend} serving process")
+            def launch(t):
+                if args.backend == "local":
+                    return LocalServingRunner().launch(cfg, port=args.port, background=args.background)
+                return ModalServingRunner().launch(cfg, deploy=args.deploy)
+            proc = tasks.run_task(task, launch)
+            return finish_launch(proc, background=args.backend == "local" and args.background)
+
+    try:
+        result = run_interactive_wizard(hw_info)
+        return result.get("exit_code", 0) if isinstance(result, dict) else 0
+    except ServingBlockedError as exc:
+        print(str(exc))
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flexsds/cli/output.py

@@ -0,0 +1,69 @@
+"""Encoding-safe presentation without reconfiguring caller-owned streams."""
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def supports_unicode(stream) -> bool:
+    """Unknown codecs/streams conservatively use ASCII."""
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        return False
+    try:
+        "\u2584\u2714\u26a0\u00b7".encode(encoding)
+    except (UnicodeEncodeError, LookupError):
+        return False
+    return True
+
+
+def supports_truecolor(stream) -> bool:
+    """Require positive terminal capability evidence, never send color to pipes."""
+    if "NO_COLOR" in os.environ or os.environ.get("TERM") == "dumb":
+        return False
+    try:
+        if not getattr(stream, "isatty", lambda: False)():
+            return False
+    except OSError:
+        return False
+    return (os.environ.get("COLORTERM", "").lower() in ("truecolor", "24bit")
+            or os.environ.get("TERM", "").endswith(("-direct", "-truecolor"))
+            or bool(os.environ.get("WT_SESSION")))
+
+
+def ascii_text(text: str) -> str:
+    """Keep status meanings; escape other unencodable content rather than omit it."""
+    text = _ANSI.sub("", text)
+    for symbol, replacement in (("\u2714", "[OK]"), ("\u26a0", "[WARN]"),
+                                ("\u00b7", "|"), ("\u2022", "*")):
+        text = text.replace(symbol, replacement)
+    return text.encode("ascii", errors="backslashreplace").decode("ascii")
+
+
+def print_output(text: str = "", *, file=None, end: str = "\n", fallback=None) -> None:
+    """Write one message; only encoding errors may cause an ASCII retry.
+
+    I/O errors such as a closed pipe propagate. The stream's encoding is never
+    changed. A supplied fallback preserves a compact banner if metadata lies.
+    """
+    stream = sys.stdout if file is None else file
+    if stream is None:
+        return
+    message = text + end
+    if not supports_truecolor(stream):
+        message = _ANSI.sub("", message)
+    if not supports_unicode(stream):
+        message = ascii_text((fallback if fallback is not None else text) + end)
+    try:
+        stream.write(message)
+    except UnicodeEncodeError:
+        stream.write(ascii_text((fallback if fallback is not None else text) + end))
+
+
+def write_output(text: str) -> None:
+    """Encoding-safe incremental output for streamed chat content."""
+    print_output(text, end="")

flexsds/cli/task_runner.py

@@ -0,0 +1,171 @@
+"""Interactive task manager with compact view and Ctrl+O toggled details."""
+from __future__ import annotations
+
+import enum
+import os
+import select
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+try:
+    from flexsds.cli.output import ascii_text, supports_unicode
+except ModuleNotFoundError:
+    from src.flexsds.cli.output import ascii_text, supports_unicode
+
+
+class TaskStatus(enum.Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class Task:
+    """Represents a discrete setup or serving execution task."""
+    name: str
+    status: TaskStatus = TaskStatus.PENDING
+    logs: List[str] = field(default_factory=list)
+    start_time: float = 0.0
+    duration: float = 0.0
+    error: Optional[str] = None
+
+    def log(self, message: str) -> None:
+        """Appends a log line to task buffer without polluting terminal."""
+        clean_msg = message.rstrip("\r\n")
+        if clean_msg:
+            self.logs.append(clean_msg)
+
+
+class TaskRunner:
+    """Orchestrates tasks, renders interactive status, and handles Ctrl+O log toggle."""
+
+    SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    def __init__(self, interactive: Optional[bool] = None) -> None:
+        self.tasks: List[Task] = []
+        self.show_details: bool = False
+        self.is_interactive = interactive if interactive is not None else sys.stdout.isatty()
+        self._current_frame_idx = 0
+        self._listener_thread: Optional[threading.Thread] = None
+        self._stop_listener = threading.Event()
+
+    def add_task(self, name: str) -> Task:
+        """Enqueues a new task."""
+        task = Task(name=name)
+        self.tasks.append(task)
+        return task
+
+    def toggle_details(self) -> None:
+        """Toggles between compact task list and expanded log details."""
+        self.show_details = not self.show_details
+
+    def handle_key(self, key: str) -> bool:
+        """Handles keypress events (Ctrl+O is ASCII 0x0F)."""
+        if key == "\x0f" or key == "\x0e":  # Ctrl+O (or Ctrl+N alternative)
+            self.toggle_details()
+            return True
+        return False
+
+    def render_view(self) -> str:
+        """Renders current status of all tasks with optional log detail box."""
+        lines: List[str] = []
+        active_task: Optional[Task] = None
+
+        for idx, t in enumerate(self.tasks, 1):
+            if t.status == TaskStatus.COMPLETED:
+                icon = "\033[32m✔\033[0m"
+                dur_str = f" \033[90m({t.duration:.1f}s)\033[0m"
+                lines.append(f"  {icon} [{idx}/{len(self.tasks)}] {t.name}{dur_str}")
+            elif t.status == TaskStatus.RUNNING:
+                active_task = t
+                spinner = self.SPINNER_FRAMES[self._current_frame_idx % len(self.SPINNER_FRAMES)]
+                icon = f"\033[36m{spinner}\033[0m"
+                elapsed = max(time.perf_counter() - t.start_time, 0.0) if t.start_time > 0 else 0.0
+                dur_str = f" \033[33m({elapsed:.1f}s)\033[0m"
+                lines.append(f"  {icon} [{idx}/{len(self.tasks)}] \033[1m{t.name}\033[0m{dur_str}")
+            elif t.status == TaskStatus.FAILED:
+                active_task = t
+                icon = "\033[31m✖\033[0m"
+                lines.append(f"  {icon} [{idx}/{len(self.tasks)}] \033[31m{t.name}\033[0m")
+            else:
+                icon = "\033[90m○\033[0m"
+                lines.append(f"  {icon} [{idx}/{len(self.tasks)}] \033[90m{t.name}\033[0m")
+
+        # Footer hướng dẫn phím tắt
+        if self.show_details:
+            footer = "  \033[90m[\033[36mCtrl+O\033[90m: Thu gọn chi tiết log | \033[36mCtrl+C\033[90m: Dừng]\033[0m"
+        else:
+            footer = "  \033[90m[\033[36mCtrl+O\033[90m: Xem chi tiết tác vụ | \033[36mCtrl+C\033[90m: Dừng]\033[0m"
+
+        lines.append("")
+        lines.append(footer)
+
+        # Nếu chế độ mở rộng đang bật, hiển thị khung log của tác vụ đang chạy hoặc vừa chạy
+        if self.show_details and active_task and active_task.logs:
+            lines.append("")
+            lines.append(f"  \033[90m┌─── \033[1;37mNhật ký tác vụ: {active_task.name}\033[0m \033[90m" + "─" * 30 + "┐\033[0m")
+            recent_logs = active_task.logs[-8:]  # Hiển thị 8 dòng gần nhất
+            for log_line in recent_logs:
+                lines.append(f"  \033[90m│\033[0m \033[90m{log_line[:76]}\033[0m")
+            lines.append("  \033[90m└" + "─" * 60 + "┘\033[0m")
+
+        view = "\n".join(lines)
+        return view if supports_unicode(sys.stdout) else ascii_text(view)
+
+    def _start_key_listener(self) -> None:
+        """Starts background non-blocking key listener for Ctrl+O."""
+        if not self.is_interactive or not sys.stdin.isatty():
+            return
+
+        def _listen() -> None:
+            try:
+                import termios
+                import tty
+
+                old_settings = termios.tcgetattr(sys.stdin)
+                tty.setcbreak(sys.stdin.fileno())
+                try:
+                    while not self._stop_listener.is_set():
+                        # Kiểm tra xem có dữ liệu stdin trong 0.1 giây không
+                        rlist, _, _ = select.select([sys.stdin], [], [], 0.1)
+                        if rlist:
+                            ch = sys.stdin.read(1)
+                            if ch:
+                                self.handle_key(ch)
+                finally:
+                    termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
+            except Exception:
+                pass
+
+        self._stop_listener.clear()
+        self._listener_thread = threading.Thread(target=_listen, daemon=True)
+        self._listener_thread.start()
+
+    def _stop_key_listener(self) -> None:
+        """Stops background key listener."""
+        self._stop_listener.set()
+        if self._listener_thread and self._listener_thread.is_alive():
+            self._listener_thread.join(timeout=0.3)
+
+    def run_task(self, task: Task, action: Callable[[Task], Any]) -> Any:
+        """Executes a single task with live status updates."""
+        task.status = TaskStatus.RUNNING
+        task.start_time = time.perf_counter()
+        self._start_key_listener()
+
+        try:
+            result = action(task)
+            task.duration = max(time.perf_counter() - task.start_time, 0.0)
+            task.status = TaskStatus.COMPLETED
+            return result
+        except Exception as e:
+            task.duration = max(time.perf_counter() - task.start_time, 0.0)
+            task.status = TaskStatus.FAILED
+            task.error = str(e)
+            raise
+        finally:
+            self._stop_key_listener()