mlx-stack 0.1.0__py3-none-any.whl

mlx_stack/cli/init.py

@@ -0,0 +1,180 @@
+"""CLI command for stack initialization — `mlx-stack init`.
+
+Generates stack definition and LiteLLM configuration files from a
+hardware profile and recommendation. Supports --accept-defaults for
+non-interactive mode, --intent, --add/--remove for customization,
+and --force for overwriting existing configs.
+"""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from mlx_stack.core.stack_init import InitError, run_init
+
+console = Console(stderr=True)
+
+
+def _display_summary(result: dict) -> None:
+    """Display a summary of the generated configuration.
+
+    Shows file paths, tier assignments, total estimated memory,
+    and next-step instructions.
+
+    Args:
+        result: The result dict from run_init.
+    """
+    out = Console()
+    stack = result["stack"]
+    profile = result["profile"]
+
+    out.print()
+    out.print(Text("✅ Stack initialized successfully!", style="bold green"))
+    out.print()
+
+    # File paths
+    out.print(Text("Generated files:", style="bold"))
+    out.print(f"  Stack:   {result['stack_path']}")
+    out.print(f"  LiteLLM: {result['litellm_path']}")
+    out.print()
+
+    # Tier assignments table
+    out.print(Text("Tier assignments:", style="bold"))
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Tier", style="bold", min_width=12)
+    table.add_column("Model", min_width=20)
+    table.add_column("Quant", min_width=6)
+    table.add_column("Port", justify="right", min_width=6)
+
+    for tier in stack["tiers"]:
+        table.add_row(
+            tier["name"],
+            tier["model"],
+            tier["quant"],
+            str(tier["port"]),
+        )
+
+    out.print(table)
+
+    # Hardware and memory summary
+    out.print()
+    budget_gb = result["memory_budget_gb"]
+    total_memory_gb = result.get("total_memory_gb", 0.0)
+    out.print(
+        f"[dim]Hardware: {profile.chip} ({profile.memory_gb} GB) · "
+        f"Budget: {budget_gb:.1f} GB[/dim]"
+    )
+    if total_memory_gb > 0:
+        out.print(
+            f"[dim]Total estimated memory: {total_memory_gb:.1f} GB[/dim]"
+        )
+
+    # Warnings (e.g., memory budget exceeded with --add)
+    init_warnings = result.get("warnings", [])
+    if init_warnings:
+        out.print()
+        for warning in init_warnings:
+            out.print(f"[yellow]⚠ {warning}[/yellow]")
+
+    # Cloud fallback indicator
+    if stack.get("cloud_fallback"):
+        out.print()
+        out.print(
+            "[bold green]☁ Cloud Fallback[/bold green]  "
+            "Premium tier via OpenRouter configured"
+        )
+
+    # Missing models warning
+    missing = result.get("missing_models", [])
+    if missing:
+        out.print()
+        out.print("[yellow]⚠ Missing local models:[/yellow]")
+        for model_id in missing:
+            out.print(f"  • {model_id}")
+        out.print()
+        out.print(
+            "  Run [bold]mlx-stack pull[/bold] to download missing models "
+            "before starting the stack."
+        )
+
+    # Next steps
+    out.print()
+    out.print(Text("Next steps:", style="bold"))
+    if missing:
+        out.print("  1. [bold]mlx-stack pull[/bold]  — Download missing models")
+        out.print("  2. [bold]mlx-stack up[/bold]    — Start all services")
+    else:
+        out.print("  1. [bold]mlx-stack up[/bold]  — Start all services")
+    out.print()
+
+
+@click.command()
+@click.option(
+    "--accept-defaults",
+    is_flag=True,
+    default=False,
+    help="Use defaults without prompting (balanced intent, default budget).",
+)
+@click.option(
+    "--intent",
+    type=str,
+    default=None,
+    help="Recommendation intent: balanced (default) or agent-fleet.",
+)
+@click.option(
+    "--add",
+    "add_models",
+    multiple=True,
+    help="Add a model to the stack (can be specified multiple times).",
+)
+@click.option(
+    "--remove",
+    "remove_tiers",
+    multiple=True,
+    help="Remove a tier from the stack (can be specified multiple times).",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Overwrite existing stack configuration.",
+)
+def init(
+    accept_defaults: bool,
+    intent: str | None,
+    add_models: tuple[str, ...],
+    remove_tiers: tuple[str, ...],
+    force: bool,
+) -> None:
+    """Generate stack definition and LiteLLM config.
+
+    Creates ~/.mlx-stack/stacks/default.yaml with tier assignments
+    and ~/.mlx-stack/litellm.yaml with proxy configuration.
+
+    Use --accept-defaults for non-interactive mode. Combine with
+    --intent to specify the optimization strategy.
+
+    Use --add to include additional models and --remove to exclude
+    specific tiers from the default recommendation.
+
+    Requires --force to overwrite an existing stack configuration.
+    """
+    # Default intent
+    if intent is None:
+        intent = "balanced"
+
+    try:
+        result = run_init(
+            intent=intent,
+            add_models=list(add_models) if add_models else None,
+            remove_tiers=list(remove_tiers) if remove_tiers else None,
+            force=force,
+        )
+    except InitError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+
+    _display_summary(result)

mlx_stack/cli/install.py

@@ -0,0 +1,165 @@
+"""CLI commands for launchd integration — `mlx-stack install` and `mlx-stack uninstall`.
+
+Manages the watchdog as a macOS LaunchAgent, enabling automatic startup
+on login and persistent health monitoring.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+from rich.text import Text
+
+from mlx_stack.core.launchd import (
+    AgentStatus,
+    LaunchdError,
+    PlatformError,
+    PrerequisiteError,
+    check_platform,
+    get_agent_status,
+    install_agent,
+    uninstall_agent,
+)
+
+console = Console(stderr=True)
+
+
+# --------------------------------------------------------------------------- #
+# Status display helper
+# --------------------------------------------------------------------------- #
+
+
+def _display_status(status: AgentStatus) -> None:
+    """Display the agent status in Rich format.
+
+    Args:
+        status: The current agent status.
+    """
+    out = Console()
+
+    if not status.installed:
+        out.print(Text("Status: not installed", style="dim"))
+    elif status.running and status.pid is not None:
+        out.print(
+            Text(f"Status: installed and running (PID {status.pid})", style="green")
+        )
+    else:
+        out.print(Text("Status: installed but not running", style="yellow"))
+
+
+# --------------------------------------------------------------------------- #
+# install command
+# --------------------------------------------------------------------------- #
+
+
+@click.command()
+@click.option(
+    "--status",
+    "show_status",
+    is_flag=True,
+    default=False,
+    help="Show the current launchd agent status without installing.",
+)
+def install(show_status: bool) -> None:
+    """Install the watchdog as a macOS LaunchAgent.
+
+    Generates a launchd plist that runs `mlx-stack watch` automatically
+    on login. The watchdog monitors stack health and auto-restarts
+    crashed services.
+
+    \b
+    Requires:
+      • macOS (launchd is macOS-only)
+      • mlx-stack init (stack must be configured first)
+
+    \b
+    Behavior:
+      • Creates plist at ~/Library/LaunchAgents/com.mlx-stack.watchdog.plist
+      • Loads the agent immediately via launchctl bootstrap
+      • If already installed, updates the plist and reloads
+
+    \b
+    Examples:
+        mlx-stack install              Install and start the watchdog agent
+        mlx-stack install --status     Check if the agent is installed
+    """
+    # Platform guard: reject non-macOS before any branch (including --status)
+    try:
+        check_platform()
+    except PlatformError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        sys.exit(1)
+
+    if show_status:
+        status = get_agent_status()
+        _display_status(status)
+        return
+
+    try:
+        plist_path, was_reinstall = install_agent()
+
+        out = Console()
+        if was_reinstall:
+            out.print(Text("Watchdog agent updated and reloaded.", style="bold green"))
+        else:
+            out.print(Text("Watchdog agent installed successfully.", style="bold green"))
+
+        out.print(Text(f"  Plist: {plist_path}", style="dim"))
+        out.print(
+            Text(
+                "  The watchdog will start automatically on login.",
+                style="dim",
+            )
+        )
+
+    except PlatformError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        sys.exit(1)
+    except PrerequisiteError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        sys.exit(1)
+    except LaunchdError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        sys.exit(1)
+
+
+# --------------------------------------------------------------------------- #
+# uninstall command
+# --------------------------------------------------------------------------- #
+
+
+@click.command()
+def uninstall() -> None:
+    """Uninstall the watchdog LaunchAgent.
+
+    Stops the watchdog agent and removes the launchd plist. Running
+    services are not affected — only the watchdog auto-monitoring
+    is disabled.
+
+    \b
+    Examples:
+        mlx-stack uninstall            Remove the watchdog agent
+    """
+    try:
+        removed = uninstall_agent()
+
+        out = Console()
+        if removed:
+            out.print(Text("Watchdog agent uninstalled.", style="bold green"))
+            out.print(
+                Text(
+                    "  Running services are not affected.",
+                    style="dim",
+                )
+            )
+        else:
+            out.print(Text("Watchdog agent is not installed.", style="yellow"))
+
+    except PlatformError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        sys.exit(1)
+    except LaunchdError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        sys.exit(1)

mlx_stack/cli/logs.py

@@ -0,0 +1,234 @@
+"""CLI command for viewing and managing service logs — `mlx-stack logs`.
+
+View log content, follow in real-time, list available log files,
+trigger on-demand rotation, and view archived logs.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from mlx_stack.core.log_viewer import (
+    DEFAULT_TAIL_LINES,
+    follow_log,
+    get_available_services,
+    get_log_path,
+    list_log_files,
+    read_all_logs,
+    read_log_tail,
+    rotate_all_logs,
+    rotate_service_log,
+)
+
+console = Console(stderr=True)
+
+
+def _display_log_list() -> None:
+    """Display a Rich table listing all available log files."""
+    log_files = list_log_files()
+
+    out = Console()
+    out.print()
+
+    if not log_files:
+        out.print(
+            Text(
+                "No log files found in logs directory.",
+                style="yellow",
+            )
+        )
+        out.print()
+        return
+
+    table = Table(
+        title="Available Log Files",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Name", style="bold", min_width=20)
+    table.add_column("Size", justify="right", min_width=10)
+    table.add_column("Modified", min_width=20)
+
+    for info in log_files:
+        table.add_row(info.name, info.size_display, info.modified_display)
+
+    out.print(table)
+    out.print()
+
+
+def _display_rotation_results(results: list) -> None:
+    """Display rotation results with Rich formatting.
+
+    Args:
+        results: List of RotationResult objects.
+    """
+    out = Console()
+    out.print()
+
+    any_rotated = False
+    for result in results:
+        if result.error:
+            out.print(f"[red]✗[/red] {result.service}: {result.error}")
+        elif result.rotated:
+            out.print(f"[green]✓[/green] {result.service}: rotated")
+            any_rotated = True
+        else:
+            out.print(f"[dim]–[/dim] {result.service}: no rotation needed")
+
+    if not results:
+        out.print(Text("No log files found to rotate.", style="yellow"))
+    elif not any_rotated and not any(r.error for r in results):
+        out.print()
+        out.print(Text("No rotation needed.", style="dim"))
+
+    out.print()
+
+
+@click.command()
+@click.argument("service", required=False, default=None)
+@click.option(
+    "--tail",
+    "tail_lines",
+    type=int,
+    default=None,
+    help=f"Show last N lines (default {DEFAULT_TAIL_LINES}).",
+)
+@click.option(
+    "--follow",
+    "-f",
+    is_flag=True,
+    default=False,
+    help="Follow log output in real-time (tail -f behavior).",
+)
+@click.option(
+    "--service",
+    "service_filter",
+    type=str,
+    default=None,
+    help="Filter to a specific service's log.",
+)
+@click.option(
+    "--rotate",
+    is_flag=True,
+    default=False,
+    help="Rotate eligible log files.",
+)
+@click.option(
+    "--all",
+    "show_all",
+    is_flag=True,
+    default=False,
+    help="Show archived and current logs in chronological order.",
+)
+def logs(
+    service: str | None,
+    tail_lines: int | None,
+    follow: bool,
+    service_filter: str | None,
+    rotate: bool,
+    show_all: bool,
+) -> None:
+    """View and manage service logs.
+
+    Without arguments, lists all available log files with sizes and
+    modification times.
+
+    \b
+    Examples:
+        mlx-stack logs                  List all log files
+        mlx-stack logs fast             Show last 50 lines of fast.log
+        mlx-stack logs fast --tail 100  Show last 100 lines
+        mlx-stack logs fast --follow    Stream new log content in real-time
+        mlx-stack logs --rotate         Rotate all eligible log files
+        mlx-stack logs fast --all       Show archived + current logs
+    """
+    # Resolve effective service name: argument takes precedence over --service
+    effective_service = service or service_filter
+
+    # Handle --rotate mode
+    if rotate:
+        if effective_service:
+            # Rotate only the specified service
+            available = get_available_services()
+            if available and effective_service not in available:
+                console.print(
+                    f"[red]Error:[/red] No log file found for service "
+                    f"'{effective_service}'. "
+                    f"Available services: {', '.join(available)}"
+                )
+                sys.exit(1)
+
+            result = rotate_service_log(effective_service)
+            _display_rotation_results([result])
+        else:
+            # Rotate all eligible logs
+            results = rotate_all_logs()
+            _display_rotation_results(results)
+        return
+
+    # No service specified — list log files
+    if effective_service is None:
+        _display_log_list()
+        return
+
+    # Handle --all mode: show archives + current.
+    # This must be checked BEFORE the log_path validation because
+    # read_all_logs works even when the current log file is missing
+    # (it can show archives only).
+    if show_all:
+        content = read_all_logs(effective_service)
+        if content:
+            click.echo(content)
+        else:
+            console.print(
+                Text(
+                    f"No log content found for service '{effective_service}'.",
+                    style="yellow",
+                )
+            )
+        return
+
+    # Validate service name — required for --follow, --tail, and default modes
+    log_path = get_log_path(effective_service)
+    if log_path is None:
+        available = get_available_services()
+        if available:
+            console.print(
+                f"[red]Error:[/red] No log file found for service "
+                f"'{effective_service}'. "
+                f"Available services: {', '.join(available)}"
+            )
+        else:
+            console.print(
+                f"[red]Error:[/red] No log file found for service "
+                f"'{effective_service}'. No log files exist."
+            )
+        sys.exit(1)
+
+    # Handle --follow mode
+    if follow:
+        num = tail_lines if tail_lines is not None else DEFAULT_TAIL_LINES
+        try:
+            follow_log(log_path, num_lines=num, output_callback=click.echo)
+        except KeyboardInterrupt:
+            # Belt-and-suspenders: ensure clean exit
+            pass
+        return
+
+    # Default: show tail of log
+    num = tail_lines if tail_lines is not None else DEFAULT_TAIL_LINES
+    content = read_log_tail(log_path, num_lines=num)
+    if content:
+        click.echo(content)
+    else:
+        console.print(
+            Text(
+                f"Log file for service '{effective_service}' is empty.",
+                style="yellow",
+            )
+        )