Implementation:EvolvingLMMs Lab Lmms eval TUI CLI

File: `/tmp/kapso_repo_sslb_59s/lmms_eval/tui/cli.py`

Overview

The TUI CLI module provides a command-line interface for launching the LMMs-Eval web UI. It manages the web UI build process, starts the FastAPI server via uvicorn, and automatically opens the browser to the web interface.

Key Components

Server Availability Check

def wait_for_server(url: str, timeout: float = 30.0) -> bool:
    import urllib.error
    import urllib.request

    start = time.time()
    while time.time() - start < timeout:
        try:
            urllib.request.urlopen(f"{url}/health", timeout=1)
            return True
        except (urllib.error.URLError, TimeoutError):
            time.sleep(0.3)
    return False

Polls the server health endpoint with a configurable timeout, sleeping 0.3 seconds between attempts.

Web UI Build Management

def check_web_built() -> bool:
    dist_dir = Path(__file__).parent / "web" / "dist"
    return (dist_dir / "index.html").exists()

def build_web_ui() -> bool:
    web_dir = Path(__file__).parent / "web"
    if not (web_dir / "package.json").exists():
        print("Web UI source not found", file=sys.stderr)
        return False

    print("Building web UI...")

    if not (web_dir / "node_modules").exists():
        result = subprocess.run(["npm", "install"], cwd=web_dir)
        if result.returncode != 0:
            print("Failed to install dependencies", file=sys.stderr)
            return False

    result = subprocess.run(["npm", "run", "build"], cwd=web_dir)
    if result.returncode != 0:
        print("Failed to build web UI", file=sys.stderr)
        return False

    return True

The build process: 1. Checks if the web UI is already built by looking for `dist/index.html` 2. Verifies that the web source exists (`package.json`) 3. Installs npm dependencies if `node_modules` doesn't exist 4. Runs the build command (`npm run build`)

Main Entry Point

def main() -> int:
    port = int(os.environ.get("LMMS_SERVER_PORT", "8000"))
    server_url = f"http://localhost:{port}"

    if not check_web_built():
        if not build_web_ui():
            return 1

    print(f"Starting LMMs-Eval Web UI on {server_url}")
    print(f"Server running at {server_url}")
    print("Opening browser...")
    webbrowser.open(server_url)
    print("Press Ctrl+C to stop\n")

    server_process = subprocess.Popen(
        [
            sys.executable,
            "-m",
            "uvicorn",
            "lmms_eval.tui.server:app",
            "--host",
            "0.0.0.0",
            "--port",
            str(port),
        ],
    )

    try:
        server_process.wait()
        return 0
    except KeyboardInterrupt:
        print("\nStopping server...")
        server_process.terminate()
        try:
            server_process.wait(timeout=5)
        except subprocess.TimeoutExpired:
            server_process.kill()
        return 0


if __name__ == "__main__":
    sys.exit(main())

The main function orchestrates the entire launch process: 1. Reads port from environment variable `LMMS_SERVER_PORT` (default: 8000) 2. Ensures web UI is built 3. Opens browser to the server URL 4. Starts uvicorn server for `lmms_eval.tui.server:app` 5. Handles keyboard interrupt for clean shutdown with graceful termination (5-second timeout before kill)

Design Patterns

Lazy Build Pattern

The web UI is only built if it hasn't been built before, reducing startup time for subsequent runs.

Environment-Based Configuration

The server port can be customized via the `LMMS_SERVER_PORT` environment variable, allowing flexibility without command-line arguments.

Graceful Shutdown

The KeyboardInterrupt handler ensures the server process is properly terminated with a timeout-based fallback to forceful kill.

Browser Auto-Launch

The CLI automatically opens the web interface in the default browser using the `webbrowser` module, improving user experience.

Process Isolation

The server runs in a separate subprocess, allowing the CLI to manage its lifecycle independently.

Server Configuration

The uvicorn server is configured with:

Host: `0.0.0.0` (accessible from all network interfaces)
Port: Configurable via environment variable, default 8000
App: `lmms_eval.tui.server:app` (FastAPI application)

Dependencies

subprocess: Process management for npm and uvicorn
webbrowser: Browser launching
pathlib: File path handling
os: Environment variable access
sys: Python executable path and exit codes
time: Sleep intervals
urllib: HTTP requests for health checks

Related Components

Server implementation: `lmms_eval/tui/server.py`
Web UI source: `lmms_eval/tui/web/`
Discovery module: TUI_Discovery
Principle: TUI_Command_Interface

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment