@smilintux/skmemory 0.5.0 → 0.9.2

package/skmemory/setup_wizard.py

@@ -0,0 +1,908 @@
+"""
+SKMemory Setup Wizard — Docker orchestration for SKVector & SKGraph.
+
+Detects Docker, deploys containers via ``docker compose``, verifies
+health, installs Python dependencies, and persists configuration so
+all future ``skmemory`` commands auto-connect.
+
+Cross-platform: macOS, Linux, Windows.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import CONFIG_DIR, SKMemoryConfig, save_config
+
+# ─────────────────────────────────────────────────────────
+# Docker Desktop direct download URLs
+# ─────────────────────────────────────────────────────────
+
+DOCKER_DESKTOP_DOWNLOAD = {
+    "Windows": ("https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe"),
+    "Darwin": "https://docs.docker.com/desktop/install/mac-install/",
+}
+
+# ─────────────────────────────────────────────────────────
+# Platform detection
+# ─────────────────────────────────────────────────────────
+
+DOCKER_COMPOSE_YAML = """\
+# Auto-generated by skmemory setup wizard
+# Source: skmemory/docker-compose.yml
+
+services:
+  skvector:
+    image: qdrant/qdrant:latest
+    container_name: skmemory-skvector
+    ports:
+      - "6333:6333"
+      - "6334:6334"
+    volumes:
+      - skvector_data:/qdrant/storage
+    environment:
+      - QDRANT__SERVICE__GRPC_PORT=6334
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+
+  skgraph:
+    image: falkordb/falkordb:latest
+    container_name: skmemory-skgraph
+    ports:
+      - "6379:6379"
+    volumes:
+      - skgraph_data:/data
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+
+volumes:
+  skvector_data:
+    driver: local
+  skgraph_data:
+    driver: local
+"""
+
+
+@dataclass
+class PlatformInfo:
+    """Platform and Docker availability snapshot."""
+
+    os_name: str = ""
+    docker_available: bool = False
+    compose_available: bool = False
+    compose_legacy: bool = False
+    docker_version: str = ""
+
+
+def detect_platform() -> PlatformInfo:
+    """Detect OS and Docker/Compose availability.
+
+    Returns:
+        PlatformInfo with detected values.
+    """
+    info = PlatformInfo(os_name=platform.system())
+
+    # Docker binary
+    if not shutil.which("docker"):
+        return info
+
+    # Docker daemon running?
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            return info
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return info
+
+    info.docker_available = True
+
+    # Docker version
+    try:
+        result = subprocess.run(
+            ["docker", "version", "--format", "{{.Server.Version}}"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            info.docker_version = result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+
+    # Compose v2 (docker compose)
+    try:
+        result = subprocess.run(
+            ["docker", "compose", "version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            info.compose_available = True
+            info.compose_legacy = False
+            return info
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+
+    # Compose v1 (docker-compose)
+    try:
+        result = subprocess.run(
+            ["docker-compose", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            info.compose_available = True
+            info.compose_legacy = True
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        pass
+
+    return info
+
+
+def get_docker_install_instructions(os_name: str) -> str:
+    """Return platform-specific Docker install instructions.
+
+    Args:
+        os_name: Result of ``platform.system()`` (Linux, Darwin, Windows).
+
+    Returns:
+        Human-readable install guide.
+    """
+    _instructions = {
+        "Linux": (
+            "Install Docker Engine:\n"
+            "  curl -fsSL https://get.docker.com | sh\n"
+            "  sudo usermod -aG docker $USER\n"
+            "  (log out and back in, then retry)"
+        ),
+        "Darwin": (
+            "Install Docker Desktop for macOS:\n"
+            "  https://docs.docker.com/desktop/install/mac-install/\n"
+            "  Or: brew install --cask docker"
+        ),
+        "Windows": (
+            "Install Docker Desktop for Windows:\n"
+            "  https://docs.docker.com/desktop/install/windows-install/\n"
+            "  WSL2 backend recommended."
+        ),
+    }
+    return _instructions.get(os_name, "Install Docker: https://docs.docker.com/get-docker/")
+
+
+# ─────────────────────────────────────────────────────────
+# Docker installation helpers
+# ─────────────────────────────────────────────────────────
+
+
+def _open_url_in_browser(url: str) -> None:
+    """Open *url* in the default browser — best-effort, never raises."""
+    try:
+        os_name = platform.system()
+        if os_name == "Windows":
+            os.system(f'start "" "{url}"')
+        elif os_name == "Darwin":
+            subprocess.run(["open", url], timeout=5, check=False)
+        else:
+            subprocess.run(["xdg-open", url], timeout=5, capture_output=True, check=False)
+    except Exception:
+        pass
+
+
+def _try_install_docker_linux(echo: Callable, input_fn: Callable) -> bool:
+    """Offer to run the Docker convenience install script on Linux.
+
+    Returns True only if Docker is detected running after the script.
+    """
+    echo("")
+    echo("Docker is required to run SKVector and SKGraph locally.")
+    echo("")
+    echo("Fastest install on Linux:")
+    echo("  curl -fsSL https://get.docker.com | sh")
+    echo("  sudo usermod -aG docker $USER   (then log out and back in)")
+    echo("")
+    ans = input_fn("Run the Docker install script now? [y/N] ").strip().lower()
+    if ans not in ("y", "yes"):
+        echo("")
+        echo("Run it yourself when ready, then come back:")
+        echo("  skmemory setup wizard")
+        return False
+
+    echo("Running Docker install script (this may take a minute)...")
+    try:
+        result = subprocess.run(
+            "curl -fsSL https://get.docker.com | sh",
+            shell=True,
+            timeout=300,
+        )
+        if result.returncode != 0:
+            echo("Docker install script failed. Please install manually.")
+            return False
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        echo(f"Installation error: {exc}")
+        return False
+
+    echo("")
+    echo("Docker installed!")
+    echo("Add yourself to the docker group, then log out/in and re-run the wizard:")
+    echo("  sudo usermod -aG docker $USER")
+    echo("  skmemory setup wizard")
+    # The current shell session needs a new group — require re-run.
+    return False
+
+
+def _try_install_docker_macos(echo: Callable, input_fn: Callable) -> bool:
+    """Offer Homebrew install or open Docker Desktop download on macOS.
+
+    Returns True only if Docker is detected running after install.
+    """
+    echo("")
+    echo("Docker Desktop is required to run SKVector and SKGraph locally.")
+    echo("")
+
+    has_brew = shutil.which("brew") is not None
+    if has_brew:
+        echo("Option 1 — Install via Homebrew (recommended):")
+        echo("  brew install --cask docker")
+        echo("")
+        echo("Option 2 — Download Docker Desktop:")
+        echo(f"  {DOCKER_DESKTOP_DOWNLOAD['Darwin']}")
+        echo("")
+        ans = input_fn("Install via Homebrew now? [Y/n] ").strip().lower()
+        if ans in ("", "y", "yes"):
+            echo("Running: brew install --cask docker  (may take a few minutes)")
+            try:
+                subprocess.run(
+                    ["brew", "install", "--cask", "docker"],
+                    timeout=600,
+                    check=False,
+                )
+            except (subprocess.TimeoutExpired, OSError) as exc:
+                echo(f"Homebrew install error: {exc}")
+            echo("")
+            echo("Docker Desktop installed! Launch it from Applications,")
+            echo("wait for the whale icon in the menu bar, then run:")
+            echo("  skmemory setup wizard")
+            return False
+        # User said no to Homebrew — fall through to browser option.
+
+    url = DOCKER_DESKTOP_DOWNLOAD["Darwin"]
+    echo(f"Docker Desktop for macOS: {url}")
+    echo("")
+    ans = input_fn("Open download page in your browser? [Y/n] ").strip().lower()
+    if ans in ("", "y", "yes"):
+        _open_url_in_browser(url)
+        echo("Download page opened.")
+    echo("After installing Docker Desktop, run: skmemory setup wizard")
+    return False
+
+
+def _try_install_docker_windows(echo: Callable, input_fn: Callable) -> bool:
+    """Offer winget install or open Docker Desktop download on Windows.
+
+    Returns True only if Docker is detected running after install.
+    """
+    echo("")
+    echo("Docker Desktop for Windows is required to run SKVector and SKGraph locally.")
+    echo("WSL2 backend is recommended (selected automatically during install).")
+    echo("")
+
+    installer_url = DOCKER_DESKTOP_DOWNLOAD["Windows"]
+    has_winget = shutil.which("winget") is not None
+
+    if has_winget:
+        echo("Option 1 — Install via Windows Package Manager (winget):")
+        echo("  winget install --id Docker.DockerDesktop")
+        echo("")
+        echo("Option 2 — Download the installer directly:")
+        echo(f"  {installer_url}")
+        echo("")
+        ans = input_fn("Install via winget now? [Y/n] ").strip().lower()
+        if ans in ("", "y", "yes"):
+            echo("Running winget install Docker.DockerDesktop ...")
+            echo("(This may take several minutes. Admin elevation may be required.)")
+            try:
+                result = subprocess.run(
+                    [
+                        "winget",
+                        "install",
+                        "--id",
+                        "Docker.DockerDesktop",
+                        "--source",
+                        "winget",
+                        "--accept-package-agreements",
+                        "--accept-source-agreements",
+                    ],
+                    timeout=600,
+                    check=False,
+                )
+                if result.returncode == 0:
+                    echo("")
+                    echo("Docker Desktop installed!")
+                    echo("Please restart your computer, then start Docker Desktop")
+                    echo("(look for the whale icon in the system tray), then run:")
+                    echo("  skmemory setup wizard")
+                    return False
+                else:
+                    echo("winget install failed. Opening the download page...")
+                    _open_url_in_browser(installer_url)
+                    echo("Download the installer, run it, restart, then:")
+                    echo("  skmemory setup wizard")
+                    return False
+            except (subprocess.TimeoutExpired, OSError) as exc:
+                echo(f"winget error: {exc}")
+                echo(f"Download manually: {installer_url}")
+                return False
+
+    # No winget — offer browser download.
+    echo("Download Docker Desktop for Windows:")
+    echo(f"  {installer_url}")
+    echo("")
+    echo("After installing:")
+    echo("  1. Restart your computer")
+    echo("  2. Start Docker Desktop (whale icon in system tray)")
+    echo("  3. Run: skmemory setup wizard")
+    echo("")
+    ans = input_fn("Open the download page in your browser? [Y/n] ").strip().lower()
+    if ans in ("", "y", "yes"):
+        _open_url_in_browser(installer_url)
+        echo("Download page opened in browser.")
+    return False
+
+
+def try_install_docker(
+    os_name: str,
+    echo: Callable,
+    input_fn: Callable | None = None,
+) -> bool:
+    """Offer to help the user install Docker for their OS.
+
+    Args:
+        os_name: Result of ``platform.system()`` (Linux, Darwin, Windows).
+        echo: Output callable.
+        input_fn: Input callable (defaults to built-in ``input``).
+
+    Returns:
+        True if Docker is now available (rare — most paths require a re-run
+        after install/reboot), False otherwise.
+    """
+    if input_fn is None:
+        input_fn = input
+
+    if os_name == "Linux":
+        return _try_install_docker_linux(echo, input_fn)
+    if os_name == "Darwin":
+        return _try_install_docker_macos(echo, input_fn)
+    if os_name == "Windows":
+        return _try_install_docker_windows(echo, input_fn)
+
+    echo("")
+    echo("Docker not found. Install it from: https://docs.docker.com/get-docker/")
+    echo("Then run: skmemory setup wizard")
+    return False
+
+
+def check_port_available(port: int) -> bool:
+    """Test if a TCP port is available for binding.
+
+    Args:
+        port: Port number to check.
+
+    Returns:
+        True if the port is free, False if occupied.
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", port))
+            return True
+    except OSError:
+        return False
+
+
+# ─────────────────────────────────────────────────────────
+# Container lifecycle
+# ─────────────────────────────────────────────────────────
+
+
+def _compose_cmd(use_legacy: bool) -> list[str]:
+    """Return the base compose command based on version."""
+    if use_legacy:
+        return ["docker-compose"]
+    return ["docker", "compose"]
+
+
+def find_compose_file() -> Path:
+    """Locate the docker-compose.yml.
+
+    Checks:
+    1. Package-bundled compose file (next to this source file's parent).
+    2. Falls back to generating one in ``~/.skcapstone/docker-compose.yml``.
+
+    Returns:
+        Path to the compose file.
+    """
+    # Check package-bundled location
+    package_dir = Path(__file__).resolve().parent.parent
+    bundled = package_dir / "docker-compose.yml"
+    if bundled.exists():
+        return bundled
+
+    # Fall back to ~/.skcapstone/
+    fallback = CONFIG_DIR / "docker-compose.yml"
+    if not fallback.exists():
+        fallback.parent.mkdir(parents=True, exist_ok=True)
+        fallback.write_text(DOCKER_COMPOSE_YAML)
+    return fallback
+
+
+def compose_up(
+    services: list[str] | None = None,
+    compose_file: Path | None = None,
+    use_legacy: bool = False,
+) -> subprocess.CompletedProcess:
+    """Start containers via docker compose.
+
+    Args:
+        services: Specific services to start (None = all).
+        compose_file: Path to compose file.
+        use_legacy: Use ``docker-compose`` instead of ``docker compose``.
+
+    Returns:
+        CompletedProcess from the subprocess call.
+    """
+    if compose_file is None:
+        compose_file = find_compose_file()
+
+    cmd = _compose_cmd(use_legacy) + ["-f", str(compose_file), "up", "-d"]
+    if services:
+        cmd.extend(services)
+
+    return subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+
+
+def compose_down(
+    compose_file: Path | None = None,
+    remove_volumes: bool = False,
+    use_legacy: bool = False,
+) -> subprocess.CompletedProcess:
+    """Stop and remove containers.
+
+    Args:
+        compose_file: Path to compose file.
+        remove_volumes: Also remove data volumes.
+        use_legacy: Use ``docker-compose`` instead of ``docker compose``.
+
+    Returns:
+        CompletedProcess from the subprocess call.
+    """
+    if compose_file is None:
+        compose_file = find_compose_file()
+
+    cmd = _compose_cmd(use_legacy) + ["-f", str(compose_file), "down"]
+    if remove_volumes:
+        cmd.append("-v")
+
+    return subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+
+
+def compose_ps(
+    compose_file: Path | None = None,
+    use_legacy: bool = False,
+) -> subprocess.CompletedProcess:
+    """Show container status.
+
+    Args:
+        compose_file: Path to compose file.
+        use_legacy: Use ``docker-compose`` instead of ``docker compose``.
+
+    Returns:
+        CompletedProcess from the subprocess call.
+    """
+    if compose_file is None:
+        compose_file = find_compose_file()
+
+    cmd = _compose_cmd(use_legacy) + ["-f", str(compose_file), "ps"]
+    return subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+
+
+# ─────────────────────────────────────────────────────────
+# Health checks
+# ─────────────────────────────────────────────────────────
+
+
+def check_skvector_health(url: str = "http://localhost:6333", timeout: int = 30) -> bool:
+    """Poll SKVector's /healthz endpoint until healthy or timeout.
+
+    Args:
+        url: SKVector (Qdrant) REST API base URL.
+        timeout: Max seconds to wait.
+
+    Returns:
+        True if SKVector responded healthy within the timeout.
+    """
+    deadline = time.monotonic() + timeout
+    healthz = f"{url.rstrip('/')}/healthz"
+
+    while time.monotonic() < deadline:
+        try:
+            req = urllib.request.Request(healthz, method="GET")
+            with urllib.request.urlopen(req, timeout=3) as resp:
+                if resp.status == 200:
+                    return True
+        except (urllib.error.URLError, OSError, TimeoutError):
+            pass
+        time.sleep(2)
+
+    return False
+
+
+def check_skgraph_health(host: str = "localhost", port: int = 6379, timeout: int = 30) -> bool:
+    """Send Redis PING to SKGraph and wait for PONG.
+
+    Args:
+        host: SKGraph (FalkorDB) hostname.
+        port: SKGraph port (Redis protocol).
+        timeout: Max seconds to wait.
+
+    Returns:
+        True if PONG received within the timeout.
+    """
+    deadline = time.monotonic() + timeout
+
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=3) as sock:
+                sock.sendall(b"PING\r\n")
+                data = sock.recv(64)
+                if b"+PONG" in data:
+                    return True
+        except (OSError, TimeoutError):
+            pass
+        time.sleep(2)
+
+    return False
+
+
+# ─────────────────────────────────────────────────────────
+# Dependency installer
+# ─────────────────────────────────────────────────────────
+
+
+def install_python_deps(backends: list[str]) -> subprocess.CompletedProcess:
+    """Install Python packages for the selected backends.
+
+    Args:
+        backends: List of backend names (``"skvector"``, ``"skgraph"``).
+
+    Returns:
+        CompletedProcess from pip.
+    """
+    packages: list[str] = []
+    if "skvector" in backends:
+        packages.extend(["qdrant-client", "sentence-transformers"])
+    if "skgraph" in backends:
+        packages.append("falkordb")
+
+    if not packages:
+        return subprocess.CompletedProcess(args=[], returncode=0)
+
+    cmd = [sys.executable, "-m", "pip", "install"] + packages
+    return subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+
+
+# ─────────────────────────────────────────────────────────
+# Main wizard
+# ─────────────────────────────────────────────────────────
+
+
+def run_setup_wizard(
+    enable_skvector: bool = True,
+    enable_skgraph: bool = True,
+    skip_deps: bool = False,
+    non_interactive: bool = False,
+    deployment_mode: str | None = None,
+    echo: Callable | None = None,
+    input_fn: Callable | None = None,
+) -> dict:
+    """Run the full interactive setup wizard.
+
+    Args:
+        enable_skvector: Include SKVector (vector search) backend.
+        enable_skgraph: Include SKGraph (graph db) backend.
+        skip_deps: Skip Python dependency installation.
+        non_interactive: Don't prompt — use defaults (implies local mode).
+        deployment_mode: ``"local"`` (Docker), ``"remote"`` (SaaS / custom URL),
+            or ``None`` to ask interactively.
+        echo: Callable for output (default: print).
+        input_fn: Callable for text input (default: built-in ``input``).
+
+    Returns:
+        dict with wizard results including ``success``, ``mode``,
+        ``services``, ``health``, and ``config_path``.
+    """
+    if echo is None:
+        echo = print
+    # Wrap echo so it accepts (and ignores) kwargs like end=
+    _raw_echo = echo
+
+    def echo(msg="", **kwargs):  # noqa: F811
+        _raw_echo(msg)
+
+    if input_fn is None:
+        input_fn = input
+
+    result: dict = {
+        "success": False,
+        "mode": deployment_mode or "local",
+        "services": [],
+        "health": {},
+        "config_path": None,
+        "errors": [],
+    }
+
+    echo("")
+    echo("SKMemory Setup Wizard")
+    echo("=" * 40)
+
+    # ── Step 0: local vs remote ──────────────────────────────────────────────
+    if not non_interactive and deployment_mode is None:
+        echo("")
+        echo("SKVector and SKGraph can run:")
+        echo("  [1] Locally with Docker   (private, no cloud needed)")
+        echo("  [2] Remote / SaaS URL     (Qdrant Cloud, self-hosted server, etc.)")
+        echo("")
+        choice = input_fn("Choice [1]: ").strip()
+        deployment_mode = "remote" if choice == "2" else "local"
+        result["mode"] = deployment_mode
+
+    if deployment_mode is None:
+        deployment_mode = "local"
+
+    # ── Remote / SaaS path ──────────────────────────────────────────────────
+    if deployment_mode == "remote":
+        echo("")
+        echo("Enter your remote backend URLs.")
+        echo("Press Enter to skip a backend you don't want to enable.")
+        echo("")
+
+        skvector_url: str | None = None
+        skvector_key: str | None = None
+        skgraph_url: str | None = None
+
+        if enable_skvector:
+            raw = input_fn("SKVector URL (e.g. https://xyz.cloud.qdrant.io:6333): ").strip()
+            if raw:
+                skvector_url = raw
+                key_raw = input_fn("SKVector API key (press Enter if none): ").strip()
+                skvector_key = key_raw or None
+
+        if enable_skgraph:
+            raw = input_fn("SKGraph URL (e.g. redis://myserver:6379): ").strip()
+            if raw:
+                skgraph_url = raw
+
+        if not skvector_url and not skgraph_url:
+            echo("No URLs provided. Nothing configured.")
+            result["success"] = True
+            return result
+
+        backends_remote: list[str] = []
+        if skvector_url:
+            backends_remote.append("skvector")
+        if skgraph_url:
+            backends_remote.append("skgraph")
+
+        if not skip_deps:
+            echo("Installing Python deps...", end=" ")
+            pip_result = install_python_deps(backends_remote)
+            if pip_result.returncode != 0:
+                echo("failed!")
+                echo(f"  {pip_result.stderr.strip()[:200]}")
+                result["errors"].append("pip install failed")
+            else:
+                echo("done")
+
+        cfg = SKMemoryConfig(
+            skvector_url=skvector_url,
+            skvector_key=skvector_key,
+            skgraph_url=skgraph_url,
+            backends_enabled=backends_remote,
+            setup_completed_at=datetime.now(timezone.utc).isoformat(),
+        )
+        config_path = save_config(cfg)
+        result["config_path"] = str(config_path)
+        echo(f"\nConfig saved: {config_path}")
+
+        if not any("failed" in e for e in result["errors"]):
+            result["success"] = True
+            echo("Setup complete!")
+        return result
+
+    # ── Local / Docker path ──────────────────────────────────────────────────
+    echo("Checking Docker...", end=" ")
+    plat = detect_platform()
+
+    if not plat.docker_available:
+        echo("not found!")
+
+        if non_interactive:
+            echo("")
+            echo(get_docker_install_instructions(plat.os_name))
+            result["errors"].append("Docker not available")
+            return result
+
+        # Offer to help install Docker for the user's OS.
+        installed = try_install_docker(plat.os_name, echo, input_fn)
+        if not installed:
+            result["errors"].append("Docker not available")
+            return result
+
+        # Re-detect after a successful in-process install (rare but possible).
+        plat = detect_platform()
+        if not plat.docker_available:
+            result["errors"].append("Docker still not available after install attempt")
+            return result
+
+    version_str = f" (Docker {plat.docker_version})" if plat.docker_version else ""
+    echo(f"found{version_str}")
+
+    if not plat.compose_available:
+        echo("Docker Compose... not found!")
+        echo("Install Docker Compose: https://docs.docker.com/compose/install/")
+        result["errors"].append("Docker Compose not available")
+        return result
+
+    compose_type = "v1 (legacy)" if plat.compose_legacy else "v2"
+    echo(f"Docker Compose {compose_type}... found")
+
+    if not non_interactive:
+        echo("")
+        echo("Your memory system runs with SQLite (zero infrastructure).")
+        echo("About to deploy:")
+        if enable_skvector:
+            echo("  SKVector — vector / semantic search  (~200 MB RAM, port 6333)")
+        if enable_skgraph:
+            echo("  SKGraph  — graph / relationship db   (~100 MB RAM, port 6379)")
+        echo("")
+
+    services_to_start: list[str] = []
+    if enable_skvector:
+        services_to_start.append("skvector")
+    if enable_skgraph:
+        services_to_start.append("skgraph")
+
+    if not services_to_start:
+        echo("No backends selected. Nothing to deploy.")
+        result["success"] = True
+        return result
+
+    # 3. Port checks
+    echo("Checking ports...", end=" ")
+    port_issues = []
+    if enable_skvector:
+        if not check_port_available(6333):
+            port_issues.append("6333 (SKVector REST) in use")
+        if not check_port_available(6334):
+            port_issues.append("6334 (SKVector gRPC) in use")
+    if enable_skgraph and not check_port_available(6379):
+        port_issues.append("6379 (SKGraph) in use")
+
+    if port_issues:
+        echo("conflict!")
+        for issue in port_issues:
+            echo(f"  Port {issue}")
+        echo("Stop conflicting services or adjust docker-compose.yml ports.")
+        result["errors"].append(f"Port conflicts: {', '.join(port_issues)}")
+        return result
+
+    ports_ok = []
+    if enable_skvector:
+        ports_ok.extend(["6333", "6334"])
+    if enable_skgraph:
+        ports_ok.append("6379")
+    echo(f"{', '.join(ports_ok)} available")
+
+    # 4. Deploy containers
+    compose_file = find_compose_file()
+    echo("Starting containers...", end=" ")
+    up_result = compose_up(
+        services=services_to_start,
+        compose_file=compose_file,
+        use_legacy=plat.compose_legacy,
+    )
+    if up_result.returncode != 0:
+        echo("failed!")
+        echo(f"  {up_result.stderr.strip()}")
+        result["errors"].append(f"docker compose up failed: {up_result.stderr.strip()}")
+        return result
+    echo("done")
+    result["services"] = services_to_start
+
+    # 5. Health checks
+    echo("Health checks...", end=" ")
+    health_parts = []
+    if enable_skvector:
+        start = time.monotonic()
+        skvector_ok = check_skvector_health(timeout=30)
+        elapsed = time.monotonic() - start
+        result["health"]["skvector"] = skvector_ok
+        if skvector_ok:
+            health_parts.append(f"SKVector healthy ({elapsed:.1f}s)")
+        else:
+            health_parts.append("SKVector TIMEOUT")
+            result["errors"].append("SKVector health check timed out")
+
+    if enable_skgraph:
+        start = time.monotonic()
+        skgraph_ok = check_skgraph_health(timeout=30)
+        elapsed = time.monotonic() - start
+        result["health"]["skgraph"] = skgraph_ok
+        if skgraph_ok:
+            health_parts.append(f"SKGraph healthy ({elapsed:.1f}s)")
+        else:
+            health_parts.append("SKGraph TIMEOUT")
+            result["errors"].append("SKGraph health check timed out")
+
+    echo(", ".join(health_parts))
+
+    # 6. Python deps
+    if not skip_deps:
+        echo("Installing Python deps...", end=" ")
+        pip_result = install_python_deps(services_to_start)
+        if pip_result.returncode != 0:
+            echo("failed!")
+            echo(f"  {pip_result.stderr.strip()[:200]}")
+            result["errors"].append("pip install failed")
+        else:
+            echo("done")
+
+    # 7. Save config
+    backends_enabled = []
+    if enable_skvector:
+        backends_enabled.append("skvector")
+    if enable_skgraph:
+        backends_enabled.append("skgraph")
+
+    cfg = SKMemoryConfig(
+        skvector_url="http://localhost:6333" if enable_skvector else None,
+        skgraph_url="redis://localhost:6379" if enable_skgraph else None,
+        backends_enabled=backends_enabled,
+        docker_compose_file=str(compose_file),
+        setup_completed_at=datetime.now(timezone.utc).isoformat(),
+    )
+    config_path = save_config(cfg)
+    result["config_path"] = str(config_path)
+
+    echo(f"\nConfig saved: {config_path}")
+
+    has_errors = any("timed out" in e or "failed" in e for e in result["errors"])
+    if not has_errors:
+        result["success"] = True
+        echo("Setup complete!")
+    else:
+        echo("Setup completed with warnings. Check errors above.")
+
+    return result