mlx-stack 0.1.0__py3-none-any.whl

mlx_stack/__init__.py

@@ -0,0 +1,5 @@
+"""mlx-stack: CLI control plane for local LLM infrastructure on Apple Silicon."""
+
+from mlx_stack._version import __version__
+
+__all__ = ["__version__"]

mlx_stack/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

mlx_stack/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI command group for mlx-stack."""
+
+from mlx_stack.cli.main import cli
+
+__all__ = ["cli"]

mlx_stack/cli/bench.py

@@ -0,0 +1,221 @@
+"""CLI command for benchmarking — ``mlx-stack bench``.
+
+Runs 3 iterations of 1024-token prompt + 100-token generation against
+a running tier's vllm-mlx instance or a temporary instance for a local
+model. Reports mean ± std dev for prompt_tps and gen_tps. Compares
+against catalog thresholds: PASS (<15%), WARN (15-30%), FAIL (>30%).
+
+Supports --save to persist results to ~/.mlx-stack/benchmarks/<profile_id>.json.
+"""
+
+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.benchmark import (
+    CLASSIFICATION_PASS,
+    CLASSIFICATION_WARN,
+    BenchmarkError,
+    BenchmarkResult_,
+    BenchmarkRunError,
+    BenchmarkTargetError,
+)
+from mlx_stack.core.catalog import CatalogError
+from mlx_stack.core.deps import DependencyError, DependencyInstallError
+
+console = Console(stderr=True)
+
+
+@click.command()
+@click.argument("target", required=True)
+@click.option("--save", is_flag=True, default=False, help="Save benchmark results.")
+def bench(target: str, save: bool) -> None:
+    """Benchmark a tier or model.
+
+    TARGET is a running tier name (e.g., 'fast', 'standard') or a
+    catalog model ID (e.g., 'qwen3.5-8b'). For running tiers, targets
+    the existing vllm-mlx instance. For local models, starts a temporary
+    instance with full cleanup.
+
+    Runs 3 iterations of 1024-token prompt + 100-token generation and
+    reports mean ± std dev for prompt_tps and gen_tps.
+
+    Compares against catalog benchmarks: PASS (within 15%), WARN (15-30%
+    below), FAIL (>30% below) per metric with delta percentage.
+
+    Use --save to persist results to ~/.mlx-stack/benchmarks/<profile_id>.json.
+    """
+    out = Console()
+
+    try:
+        from mlx_stack.core.benchmark import run_benchmark
+
+        result = run_benchmark(target=target, save=save)
+        _display_results(result, out, save=save)
+
+    except BenchmarkTargetError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except BenchmarkRunError as exc:
+        console.print(f"[bold red]Benchmark error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except BenchmarkError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except DependencyInstallError as exc:
+        console.print(f"[bold red]Dependency error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except DependencyError as exc:
+        console.print(f"[bold red]Dependency error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except CatalogError as exc:
+        console.print(f"[bold red]Catalog error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+
+
+def _display_results(result: BenchmarkResult_, out: Console, save: bool = False) -> None:
+    """Display benchmark results with Rich formatting.
+
+    Args:
+        result: The benchmark result to display.
+        out: Rich console for output.
+        save: Whether results were saved.
+    """
+    out.print()
+
+    # Header
+    header = Text("Benchmark Results", style="bold cyan")
+    header.append(f" — {result.model_id} ({result.quant})")
+    out.print(header)
+    out.print()
+
+    # Instance type indicator
+    if result.used_temporary_instance:
+        out.print("[dim]Using temporary vllm-mlx instance[/dim]")
+    else:
+        out.print("[dim]Using running tier instance[/dim]")
+    out.print()
+
+    # Performance results table
+    perf_table = Table(title="Performance", show_header=True, header_style="bold")
+    perf_table.add_column("Metric", style="cyan")
+    perf_table.add_column("Mean", justify="right")
+    perf_table.add_column("Std Dev", justify="right")
+
+    perf_table.add_row(
+        "Prompt TPS",
+        f"{result.prompt_tps_mean:.1f} tok/s",
+        f"± {result.prompt_tps_std:.1f}",
+    )
+    perf_table.add_row(
+        "Generation TPS",
+        f"{result.gen_tps_mean:.1f} tok/s",
+        f"± {result.gen_tps_std:.1f}",
+    )
+
+    out.print(perf_table)
+    out.print()
+
+    # Comparison against catalog
+    if result.classifications:
+        comp_table = Table(
+            title="Catalog Comparison",
+            show_header=True,
+            header_style="bold",
+        )
+        comp_table.add_column("Metric", style="cyan")
+        comp_table.add_column("Measured", justify="right")
+        comp_table.add_column("Catalog", justify="right")
+        comp_table.add_column("Delta", justify="right")
+        comp_table.add_column("Result", justify="center")
+
+        for cls in result.classifications:
+            # Color the classification
+            if cls.classification == CLASSIFICATION_PASS:
+                result_style = "[bold green]PASS[/bold green]"
+            elif cls.classification == CLASSIFICATION_WARN:
+                result_style = "[bold yellow]WARN[/bold yellow]"
+            else:
+                result_style = "[bold red]FAIL[/bold red]"
+
+            # Format delta
+            delta_str = f"{cls.delta_pct:+.1f}%"
+            if cls.delta_pct > 0:
+                delta_str = f"-{cls.delta_pct:.1f}%"  # Below catalog
+            else:
+                delta_str = f"+{abs(cls.delta_pct):.1f}%"  # Above catalog
+
+            metric_name = cls.metric.replace("_", " ").title().replace("Tps", "TPS")
+
+            comp_table.add_row(
+                metric_name,
+                f"{cls.measured:.1f}",
+                f"{cls.catalog:.1f}",
+                delta_str,
+                result_style,
+            )
+
+        out.print(comp_table)
+        out.print()
+    elif not result.catalog_data_available:
+        out.print(
+            "[yellow]No catalog benchmark data available for your hardware profile.[/yellow]\n"
+            "Use [bold]--save[/bold] to record this benchmark for future comparisons."
+        )
+        out.print()
+
+    # Tool-calling result
+    if result.tool_call_result is not None:
+        out.print(Text("Tool Calling", style="bold cyan"))
+        tc = result.tool_call_result
+        if tc.success:
+            out.print(
+                f"  [green]✓ Valid tool call[/green] — "
+                f"round-trip: {tc.round_trip_time:.2f}s"
+            )
+        else:
+            out.print(
+                f"  [red]✗ Tool call failed[/red] — {tc.error}"
+            )
+        out.print()
+    elif not result.tool_call_result:
+        # Check if model supports tool calling from entry
+        if not result.catalog_data_available:
+            pass  # Skip silently if no catalog data
+        else:
+            out.print(
+                "[dim]Tool calling: skipped (model does not support tool calling)[/dim]"
+            )
+            out.print()
+
+    # Iteration details
+    if result.iterations:
+        iter_table = Table(
+            title="Iteration Details",
+            show_header=True,
+            header_style="bold",
+        )
+        iter_table.add_column("#", style="dim", justify="right")
+        iter_table.add_column("Prompt TPS", justify="right")
+        iter_table.add_column("Gen TPS", justify="right")
+        iter_table.add_column("Time", justify="right")
+
+        for i, it in enumerate(result.iterations, 1):
+            iter_table.add_row(
+                str(i),
+                f"{it.prompt_tps:.1f}",
+                f"{it.gen_tps:.1f}",
+                f"{it.total_time:.1f}s",
+            )
+
+        out.print(iter_table)
+        out.print()
+
+    # Save confirmation
+    if save:
+        out.print("[green]✓ Results saved.[/green] "
+                  "These will be used by 'recommend' and 'init' for scoring.")
+        out.print()

mlx_stack/cli/config.py

@@ -0,0 +1,166 @@
+"""CLI commands for configuration management — `mlx-stack config`.
+
+Provides set, get, list, and reset subcommands for managing
+persistent configuration in ~/.mlx-stack/config.yaml.
+"""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from mlx_stack.core.config import (
+    ConfigCorruptError,
+    ConfigError,
+    ConfigValidationError,
+    get_all_config,
+    get_value,
+    mask_value,
+    reset_config,
+    set_value,
+)
+
+console = Console(stderr=True)
+
+
+@click.group()
+def config() -> None:
+    """Manage mlx-stack configuration."""
+
+
+@config.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str) -> None:
+    """Set a configuration value.
+
+    KEY is the config key name (e.g., default-quant, litellm-port).
+    VALUE is the value to set.
+
+    Valid keys: openrouter-key, default-quant, memory-budget-pct,
+    litellm-port, model-dir, auto-health-check.
+    """
+    try:
+        result = set_value(key, value)
+        display = mask_value(key, result)
+        console.print(f"[green]✓[/green] Set [bold]{key}[/bold] = {display}")
+    except ConfigValidationError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except ConfigCorruptError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except ConfigError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+
+
+@config.command("get")
+@click.argument("key")
+def config_get(key: str) -> None:
+    """Get a configuration value.
+
+    KEY is the config key name to retrieve.
+
+    Valid keys: openrouter-key, default-quant, memory-budget-pct,
+    litellm-port, model-dir, auto-health-check.
+    """
+    try:
+        value = get_value(key)
+        display = mask_value(key, value)
+        console.print(display)
+    except ConfigCorruptError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except ConfigError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+
+
+@config.command("list")
+def config_list() -> None:
+    """List all configuration values.
+
+    Shows a table of all config keys with their current values,
+    defaults, and whether each value is user-set or default.
+    The openrouter-key is masked for security.
+    """
+    try:
+        entries = get_all_config()
+    except ConfigCorruptError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+
+    out = Console()
+    table = Table(title="Configuration", show_header=True, header_style="bold cyan")
+    table.add_column("Key", style="bold")
+    table.add_column("Value")
+    table.add_column("Default")
+    table.add_column("Source", style="dim")
+
+    for entry in entries:
+        source_style = "[dim]default[/dim]" if entry["is_default"] else "[green]user-set[/green]"
+        value_display = entry["masked_value"]
+
+        # Show empty string as (not set) for clarity
+        if entry["name"] == "openrouter-key" and entry["is_default"]:
+            value_display = "[dim](not set)[/dim]"
+
+        default_display = str(entry["default"])
+        if entry["name"] == "openrouter-key":
+            default_display = "(not set)"
+
+        table.add_row(
+            entry["name"],
+            value_display,
+            default_display,
+            source_style,
+        )
+
+    out.print()
+    out.print(table)
+    out.print()
+
+
+@config.command("reset")
+@click.option("--yes", is_flag=True, help="Confirm reset without prompting.")
+@click.option("--force", is_flag=True, help="Alias for --yes.")
+def config_reset(yes: bool, force: bool) -> None:
+    """Reset configuration to defaults.
+
+    Removes all user-set values, restoring defaults for all keys.
+    Requires --yes or --force confirmation in non-interactive mode.
+    """
+    confirmed = yes or force
+
+    if not confirmed:
+        # Check if stdin is a TTY for interactive confirmation
+        try:
+            if click.get_text_stream("stdin").isatty():
+                confirmed = click.confirm(
+                    "Reset all configuration to defaults?", default=False
+                )
+            else:
+                console.print(
+                    "[bold red]Error:[/bold red] Reset requires --yes or --force flag "
+                    "in non-interactive mode."
+                )
+                raise SystemExit(1)
+        except (AttributeError, OSError):
+            console.print(
+                "[bold red]Error:[/bold red] Reset requires --yes or --force flag "
+                "in non-interactive mode."
+            )
+            raise SystemExit(1) from None
+
+    if not confirmed:
+        console.print("[yellow]Reset cancelled.[/yellow]")
+        return
+
+    try:
+        reset_config()
+        console.print("[green]✓[/green] Configuration reset to defaults.")
+    except ConfigError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None

mlx_stack/cli/down.py

@@ -0,0 +1,109 @@
+"""CLI command for stopping services — `mlx-stack down`.
+
+Stops all managed services, or a single tier with --tier.
+Reports per-service shutdown results including graceful vs forced.
+"""
+
+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.process import LockError
+from mlx_stack.core.stack_down import DownError, DownResult, run_down
+
+console = Console(stderr=True)
+
+
+def _display_results(result: DownResult) -> None:
+    """Display shutdown results.
+
+    Shows a table of stopped services with per-service shutdown method
+    (graceful vs forced) and cleanup information.
+
+    Args:
+        result: The DownResult from shutdown.
+    """
+    out = Console()
+    out.print()
+
+    # Warnings
+    for warning in result.warnings:
+        out.print(f"[yellow]⚠ {warning}[/yellow]")
+
+    if result.warnings:
+        out.print()
+
+    # Results table
+    table = Table(
+        title="Shutdown Summary",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Service", style="bold", min_width=12)
+    table.add_column("PID", justify="right", min_width=8)
+    table.add_column("Status", min_width=14)
+    table.add_column("Method", min_width=10)
+
+    for svc in result.services:
+        pid_str = str(svc.pid) if svc.pid is not None else "-"
+
+        # Status styling
+        if svc.status == "stopped":
+            status_display = "[bold green]stopped[/bold green]"
+        elif svc.status == "stale":
+            status_display = "[yellow]stale (cleaned)[/yellow]"
+        elif svc.status == "corrupt":
+            status_display = "[yellow]corrupt (cleaned)[/yellow]"
+        elif svc.status == "not-running":
+            status_display = "[dim]not running[/dim]"
+        else:
+            status_display = svc.status
+
+        # Method display
+        if svc.graceful is True:
+            method_display = "[green]graceful (SIGTERM)[/green]"
+        elif svc.graceful is False:
+            method_display = "[red]forced (SIGKILL)[/red]"
+        else:
+            method_display = "-"
+
+        table.add_row(svc.name, pid_str, status_display, method_display)
+
+    out.print(table)
+    out.print()
+
+
+@click.command()
+@click.option("--tier", "tier_filter", type=str, help="Stop only the specified tier.")
+def down(tier_filter: str | None) -> None:
+    """Stop all managed services.
+
+    Terminates processes in correct order: LiteLLM first, then model
+    servers in reverse startup order. Uses SIGTERM with a 10-second
+    grace period, escalating to SIGKILL if needed.
+
+    Use --tier to stop only a specific tier while leaving others running.
+    """
+    try:
+        result = run_down(
+            tier_filter=tier_filter,
+        )
+    except DownError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+    except LockError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise SystemExit(1) from None
+
+    if result.nothing_to_stop:
+        out = Console()
+        out.print()
+        out.print(Text("Nothing to stop.", style="bold yellow"))
+        out.print("[dim]No PID files found — no managed services are running.[/dim]")
+        out.print()
+        return
+
+    _display_results(result)