local-llm-ctl 0.1.0__py3-none-any.whl

llm_ctl/__init__.py

@@ -0,0 +1,3 @@
+"""llm-ctl: CLI tool to manage local LLM models."""
+
+__version__ = "0.1.0"

llm_ctl/__main__.py

@@ -0,0 +1,4 @@
+from llm_ctl.cli import cli
+
+if __name__ == "__main__":
+    cli()

llm_ctl/cli.py

@@ -0,0 +1,294 @@
+"""CLI entry point for llm-ctl."""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from .config import ConfigManager, VALID_ROLES, CONFIG_PATH
+from .models import discover_models, find_model_by_id, register_model, unregister_model
+from .server import ServerManager, StateFile
+from .utils import is_port_available, find_next_available_port
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="llm-ctl")
+def cli():
+    """Manage local LLM models and role-based server lifecycle."""
+    pass
+
+
+@cli.command("list")
+def list_models():
+    """List all available local models."""
+    models = discover_models()
+    if not models:
+        click.echo("No models found.")
+        return
+
+    click.echo(f"\n{'Model ID':<55} {'Type':<6} {'Path'}")
+    click.echo("-" * 100)
+    for model in sorted(models, key=lambda m: m["model_id"]):
+        path_display = model["path"]
+        if len(path_display) > 40:
+            path_display = "..." + path_display[-37:]
+        click.echo(f"{model['model_id']:<55} {model['type']:<6} {path_display}")
+
+    click.echo(f"\nTotal: {len(models)} model(s)")
+
+
+@cli.command()
+@click.argument("role")
+@click.argument("model_id")
+@click.option("--port", "-p", type=int, default=None, help="Override auto-assigned port")
+@click.option("--type", "-t", "model_type", type=click.Choice(["mlx", "gguf"]), default=None,
+              help="Override auto-detected model type")
+def register(role, model_id, port, model_type):
+    """Register a model to a role.
+
+    ROLE: planner, reviewer, engineer, or assistant
+
+    MODEL_ID: HuggingFace model ID (e.g., lmstudio-community/Qwen3.6-27B-MLX-6bit)
+    """
+    if role not in VALID_ROLES:
+        click.echo(f"Error: Invalid role '{role}'. Must be one of: {', '.join(sorted(VALID_ROLES))}")
+        sys.exit(1)
+
+    try:
+        config = ConfigManager()
+        discovered = discover_models()
+        model = find_model_by_id(model_id, discovered)
+        if not model:
+            click.echo(f"Error: Model not found: {model_id}")
+            click.echo("Run 'llm-ctl list' to see available models.")
+            sys.exit(1)
+
+        # Check if role is already registered
+        existing = config.get_role(role)
+        if existing:
+            click.echo(f"Role '{role}' is already registered to: {existing['model_id']}")
+            if not click.confirm("Unregister and re-register?"):
+                return
+
+        # Check for shared-model warning
+        all_roles = config.get_all_roles()
+        for other_role, other_config in all_roles.items():
+            if other_role == role:
+                continue
+            if other_config.get("model_id") == model_id:
+                click.echo(
+                    f"Warning: Role '{other_role}' is already using '{model_id}'. "
+                    f"Each role runs a separate server process, which means duplicate "
+                    f"GPU memory usage. Consider using --all with a single role or "
+                    f"assigning different models."
+                )
+                break
+
+        # Use user-specified type or auto-detected type
+        effective_type = model_type if model_type else model["type"]
+
+        # Auto-assign or use provided port
+        used_ports = {r.get("port") for r in all_roles.values() if r.get("port") and r.get("model_id") != model_id}
+        if port:
+            if not is_port_available(port):
+                click.echo(f"Error: Port {port} is not available.")
+                sys.exit(1)
+        else:
+            base_port = config.get_base_port()
+            port = find_next_available_port(start=base_port, exclude=used_ports)
+
+        role_config = {
+            "model_id": model["model_id"],
+            "path": model["path"],
+            "type": effective_type,
+            "port": port,
+        }
+        config.register_role(role, role_config)
+        click.echo(f"Registered '{model_id}' to role '{role}' on port {port} (type: {effective_type})")
+
+    except ValueError as e:
+        click.echo(f"Error: {e}")
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("role")
+def unregister(role):
+    """Unregister a model from a role."""
+    if role not in VALID_ROLES:
+        click.echo(f"Error: Invalid role '{role}'. Must be one of: {', '.join(sorted(VALID_ROLES))}")
+        sys.exit(1)
+
+    config = ConfigManager()
+    if not config.get_role(role):
+        click.echo(f"Role '{role}' is not registered.")
+        return
+
+    # Stop server if running
+    server = ServerManager()
+    server.stop(role)
+
+    config.unregister_role(role)
+    click.echo(f"Unregistered role '{role}'")
+
+
+@cli.command()
+@click.argument("role", required=False)
+@click.option("--all", "-a", "all_roles", is_flag=True, help="Start all registered role servers")
+@click.option("--timeout", "-t", type=int, default=None, help="Override startup timeout in seconds")
+def start(role, all_roles, timeout):
+    """Start the server for a role, or all roles with --all."""
+    # Guard against --all + positional role conflict
+    if all_roles and role:
+        click.echo("Error: Cannot specify both --all and a role.")
+        sys.exit(1)
+
+    server = ServerManager()
+    if timeout:
+        server.STARTUP_TIMEOUT = timeout
+    config = ConfigManager()
+
+    if all_roles:
+        results = server.start_all()
+        for r in results:
+            status_icon = "\u2713" if r["status"] == "started" else "\u2717"
+            detail = f"port {r.get('info', {}).get('port', '?')}" if r["status"] == "started" else r.get("error", "")
+            click.echo(f"  {status_icon} {r['role']}: {r['status']} {detail}")
+        return
+
+    if not role:
+        click.echo("Error: Specify a role or use --all.")
+        click.echo(f"Available roles: {', '.join(sorted(VALID_ROLES))}")
+        sys.exit(1)
+
+    if role not in VALID_ROLES:
+        click.echo(f"Error: Invalid role '{role}'. Must be one of: {', '.join(sorted(VALID_ROLES))}")
+        sys.exit(1)
+
+    role_config = config.get_role(role)
+    if not role_config:
+        click.echo(f"Error: Role '{role}' is not registered. Run 'llm-ctl register {role} <model_id>'")
+        sys.exit(1)
+
+    try:
+        state = server.start(role, role_config)
+        click.echo(f"Started {role} server (PID {state['pid']}, port {state['port']})")
+        click.echo(f"Log: {state.get('log_file', 'N/A')}")
+    except RuntimeError as e:
+        click.echo(f"Error: {e}")
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("role", required=False)
+@click.option("--all", "-a", "all_roles", is_flag=True, help="Stop all running servers")
+def stop(role, all_roles):
+    """Stop the server for a role, or all roles with --all."""
+    # Guard against --all + positional role conflict
+    if all_roles and role:
+        click.echo("Error: Cannot specify both --all and a role.")
+        sys.exit(1)
+
+    server = ServerManager()
+
+    if all_roles:
+        results = server.stop_all()
+        for r in results:
+            click.echo(f"  {r['role']}: {r['status']}")
+        return
+
+    if not role:
+        click.echo("Error: Specify a role or use --all.")
+        sys.exit(1)
+
+    stopped = server.stop(role)
+    if stopped:
+        click.echo(f"Stopped {role} server")
+    else:
+        click.echo(f"Role '{role}' server is not running")
+
+
+@cli.command()
+def status():
+    """Show status of all registered roles and their servers."""
+    config = ConfigManager()
+    server = ServerManager()
+
+    roles = config.get_all_roles()
+    if not roles:
+        click.echo("No roles registered. Run 'llm-ctl register <role> <model_id>'")
+        return
+
+    statuses = server.get_all_status()
+
+    click.echo(f"\n{'Role':<12} {'Model':<50} {'Type':<6} {'Port':<6} {'Status':<10} {'PID'}")
+    click.echo("-" * 100)
+    for s in statuses:
+        running = "running" if s["running"] else "stopped"
+        pid = str(s["pid"]) if s["pid"] else "-"
+        model_id = s.get("model_id", "-")
+        if len(model_id) > 48:
+            model_id = "..." + model_id[-45:]
+        click.echo(f"{s['role']:<12} {model_id:<50} {s.get('type', '-'):6} {str(s.get('port', '-')):<6} {running:<10} {pid}")
+
+
+@cli.command()
+@click.argument("model_id")
+@click.option("--cache-dir", default=None, help="Custom HuggingFace cache directory")
+def download(model_id, cache_dir):
+    """Download a model from HuggingFace.
+
+    MODEL_ID: HuggingFace model ID (e.g., mlx-community/Qwen3.6-27B-4bit)
+    """
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        click.echo("Error: huggingface-hub is not installed. Run: pip install huggingface-hub")
+        sys.exit(1)
+
+    click.echo(f"Downloading {model_id}...")
+    try:
+        if cache_dir:
+            cachedir = cache_dir
+        else:
+            cachedir = str(Path.home() / "models" / "huggingface" / "hub")
+
+        path = snapshot_download(
+            repo_id=model_id,
+            cache_dir=cachedir,
+        )
+        click.echo(f"Downloaded to: {path}")
+    except Exception as e:
+        click.echo(f"Error downloading model: {e}")
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("action", required=False, default="show")
+def config(action):
+    """View or edit the configuration file.
+
+    ACTION: show (default) or edit (opens in $EDITOR)
+    """
+    cfg = ConfigManager()
+
+    if action == "show":
+        data = cfg.load()
+        click.echo(json.dumps(data, indent=2))
+    elif action == "edit":
+        editor = os.environ.get("EDITOR", "vi")
+        # Ensure file exists
+        if not cfg.config_path.exists():
+            cfg.save(cfg.load())
+        subprocess.call([editor, str(cfg.config_path)])
+        click.echo(f"Config file: {cfg.config_path}")
+    else:
+        click.echo(f"Unknown action: {action}. Use 'show' or 'edit'.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

llm_ctl/config.py

@@ -0,0 +1,82 @@
+"""Configuration management for llm-ctl."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_CONFIG: Dict[str, Any] = {
+    "roles": {},
+    "defaults": {
+        "base_port": 8080,
+        "models_dirs": [
+            os.path.expanduser("~/models/huggingface/hub"),
+            os.path.expanduser("~/models"),
+        ]
+    }
+}
+
+VALID_ROLES = {"planner", "reviewer", "engineer", "assistant"}
+
+CONFIG_DIR = Path.home() / ".config" / "llm-ctl"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+
+class ConfigManager:
+    def __init__(self, config_path: Optional[str] = None):
+        self.config_path = Path(config_path) if config_path else CONFIG_PATH
+
+    def load(self) -> Dict[str, Any]:
+        if not self.config_path.exists():
+            return self._default_config()
+        with open(self.config_path, "r") as f:
+            data = json.load(f)
+        # Merge with defaults to ensure new keys appear
+        merged = json.loads(json.dumps(DEFAULT_CONFIG))
+        merged["roles"].update(data.get("roles", {}))
+        if "defaults" in data:
+            merged["defaults"].update(data["defaults"])
+        return merged
+
+    def save(self, config: Dict[str, Any]) -> None:
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+    def register_role(self, role: str, role_config: Dict[str, Any]) -> None:
+        if role not in VALID_ROLES:
+            raise ValueError(f"Invalid role '{role}'. Must be one of: {', '.join(sorted(VALID_ROLES))}")
+        config = self.load()
+        config["roles"][role] = role_config
+        self.save(config)
+
+    def unregister_role(self, role: str) -> None:
+        config = self.load()
+        if role in config["roles"]:
+            del config["roles"][role]
+            self.save(config)
+
+    def get_role(self, role: str) -> Optional[Dict[str, Any]]:
+        config = self.load()
+        return config["roles"].get(role)
+
+    def get_all_roles(self) -> Dict[str, Any]:
+        config = self.load()
+        return config["roles"]
+
+    def get_base_port(self) -> int:
+        config = self.load()
+        return config["defaults"].get("base_port", 8080)
+
+    def get_models_dirs(self) -> list:
+        config = self.load()
+        return config["defaults"].get("models_dirs", DEFAULT_CONFIG["defaults"]["models_dirs"])
+
+    @staticmethod
+    def _default_config() -> Dict[str, Any]:
+        return json.loads(json.dumps(DEFAULT_CONFIG))
+
+    @property
+    def path(self) -> Path:
+        return self.config_path

llm_ctl/models.py

@@ -0,0 +1,247 @@
+"""Model discovery and management for llm-ctl."""
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+from huggingface_hub.constants import HF_HUB_CACHE as HF_DEFAULT_CACHE
+
+from .config import ConfigManager
+from .utils import expand_path, find_next_available_port
+
+
+def parse_hf_cache_dir(dir_name: str) -> Tuple[str, str]:
+    """Parse a HuggingFace cache directory name into (user, repo).
+
+    Format: models--<user>--<repo>
+    """
+    parts = dir_name.split("--")
+    if len(parts) < 3 or parts[0] != "models":
+        raise ValueError(f"Invalid HF cache directory name: {dir_name}")
+    # Rejoin in case repo name contains '--'
+    user = parts[1]
+    repo = "--".join(parts[2:])
+    return user, repo
+
+
+def resolve_hf_model_path(cache_dir: Path) -> Optional[str]:
+    """Resolve the actual model path from a HF cache directory.
+
+    Follows: cache_dir/refs/main → snapshots/<commit_hash>
+    """
+    refs_file = cache_dir / "refs" / "main"
+    if not refs_file.exists():
+        # Try other common refs
+        for ref_name in ["head", "main"]:
+            ref = cache_dir / "refs" / ref_name
+            if ref.exists():
+                refs_file = ref
+                break
+        else:
+            return None
+
+    commit_hash = refs_file.read_text().strip()
+    snapshots_dir = cache_dir / "snapshots" / commit_hash
+    if snapshots_dir.is_dir():
+        return str(snapshots_dir)
+
+    # Fallback: find any snapshot directory
+    snapshots_base = cache_dir / "snapshots"
+    if snapshots_base.is_dir():
+        for d in sorted(snapshots_base.iterdir()):
+            if d.is_dir():
+                return str(d)
+
+    return None
+
+
+def is_mlx_model(model_path: str) -> bool:
+    """Check if a model directory contains MLX-specific model files.
+    
+    Checks for MLX-specific indicators rather than generic HF files:
+    - model.mlxfmt.json (MLX format descriptor)
+    - weights.npz (MLX native weight format)
+    - *.safetensors files with MLX architecture in config
+    """
+    path = Path(model_path)
+    # MLX-specific files — these are NOT used by standard transformers models
+    mlx_indicators = [
+        path / "model.mlxfmt.json",
+        path / "weights.npz",
+    ]
+    if any(f.exists() for f in mlx_indicators):
+        return True
+    
+    # Check for safetensors + MLX architecture in config.json
+    has_safetensors = any(path.glob("*.safetensors")) or (path / "model.safetensors.index.json").exists()
+    if has_safetensors:
+        config_file = path / "config.json"
+        if config_file.exists():
+            try:
+                with open(config_file) as f:
+                    config = json.load(f)
+                arch = config.get("architectures", [])
+                if any("MLP" in a or "MLX" in a for a in arch):
+                    return True
+            except (json.JSONDecodeError, IOError):
+                pass
+    
+    return False
+
+
+def detect_model_type(model_path: str) -> str:
+    """Detect whether a model is MLX or GGUF."""
+    path = Path(model_path)
+    if path.suffix.lower() == ".gguf":
+        return "gguf"
+    if is_mlx_model(model_path):
+        return "mlx"
+    return "unknown"
+
+
+def is_hf_cache_dir(dir_path: Path) -> bool:
+    """Check if a directory is a HuggingFace hub cache directory.
+    
+    Uses the huggingface_hub constant for the default cache location,
+    and falls back to checking for models--* subdirectories.
+    """
+    # Check if this is the known HF cache dir (or a subdirectory of it)
+    expanded_hf_cache = Path(expand_path(HF_DEFAULT_CACHE))
+    try:
+        dir_path.resolve().relative_to(expanded_hf_cache.resolve())
+        return True
+    except ValueError:
+        pass
+    
+    # Check if the dir itself contains models--* entries
+    if any(
+        d.is_dir() and d.name.startswith("models--")
+        for d in dir_path.iterdir() if d.is_dir()
+    ):
+        return True
+    
+    return False
+
+
+def scan_hf_cache(hf_cache_dir: str) -> List[Dict]:
+    """Scan the HuggingFace cache directory for available models."""
+    models = []
+    cache_path = Path(expand_path(hf_cache_dir))
+    if not cache_path.is_dir():
+        return models
+
+    for entry in cache_path.iterdir():
+        if not entry.is_dir() or entry.name.startswith("."):
+            continue
+        try:
+            user, repo = parse_hf_cache_dir(entry.name)
+        except ValueError:
+            continue
+
+        model_path = resolve_hf_model_path(entry)
+        if not model_path:
+            continue
+
+        model_type = detect_model_type(model_path)
+        if model_type == "unknown":
+            continue
+
+        models.append({
+            "model_id": f"{user}/{repo}",
+            "path": model_path,
+            "type": model_type,
+        })
+
+    return models
+
+
+def scan_gguf_models(gguf_dir: str) -> List[Dict]:
+    """Scan a directory for GGUF model files."""
+    models = []
+    dir_path = Path(expand_path(gguf_dir))
+    if not dir_path.is_dir():
+        return models
+
+    for gguf_file in dir_path.glob("*.gguf"):
+        model_id = f"local/{gguf_file.name}"
+        models.append({
+            "model_id": model_id,
+            "path": str(gguf_file),
+            "type": "gguf",
+        })
+
+    return models
+
+
+def discover_models(models_dirs: Optional[List[str]] = None) -> List[Dict]:
+    """Discover all available local models."""
+    config = ConfigManager()
+    if models_dirs is None:
+        models_dirs = config.get_models_dirs()
+
+    all_models = []
+    for models_dir in models_dirs:
+        expanded = expand_path(models_dir)
+        dir_path = Path(expanded)
+        if not dir_path.is_dir():
+            continue
+
+        # Use robust HF cache detection instead of hardcoded "hub" check
+        if is_hf_cache_dir(dir_path):
+            all_models.extend(scan_hf_cache(expanded))
+        else:
+            # Scan for GGUF files
+            all_models.extend(scan_gguf_models(expanded))
+
+    # Deduplicate by path
+    seen_paths = set()
+    unique_models = []
+    for model in all_models:
+        if model["path"] not in seen_paths:
+            seen_paths.add(model["path"])
+            unique_models.append(model)
+
+    return unique_models
+
+
+def find_model_by_id(model_id: str, discovered: Optional[List[Dict]] = None) -> Optional[Dict]:
+    """Find a model by its model_id from discovered models."""
+    if discovered is None:
+        discovered = discover_models()
+    for model in discovered:
+        if model["model_id"] == model_id:
+            return model
+    return None
+
+
+def register_model(role: str, model_id: str) -> Dict:
+    """Register a model to a role in the config.
+
+    Returns the role config that was saved.
+    """
+    discovered = discover_models()
+    model = find_model_by_id(model_id, discovered)
+    if not model:
+        raise ValueError(f"Model not found: {model_id}. Run 'llm-ctl list' to see available models.")
+
+    config = ConfigManager()
+    # Auto-assign port using the consolidated utility function
+    used_ports = {r.get("port") for r in config.get_all_roles().values() if r.get("port")}
+    base_port = config.get_base_port()
+    port = find_next_available_port(start=base_port, exclude=used_ports)
+
+    role_config = {
+        "model_id": model["model_id"],
+        "path": model["path"],
+        "type": model["type"],
+        "port": port,
+    }
+    config.register_role(role, role_config)
+    return role_config
+
+
+def unregister_model(role: str) -> None:
+    """Unregister a model from a role."""
+    config = ConfigManager()
+    config.unregister_role(role)

llm_ctl/server.py

@@ -0,0 +1,263 @@
+"""Server lifecycle management for llm-ctl."""
+
+import json
+import os
+import signal
+import subprocess
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .config import ConfigManager
+from .utils import is_process_running, wait_for_port_ready, expand_path
+
+STATE_DIR = Path.home() / ".config" / "llm-ctl"
+STATE_PATH = STATE_DIR / "state.json"
+
+
+class StateFile:
+    """Manages the runtime state file tracking running servers."""
+
+    def __init__(self, state_path: Optional[str] = None):
+        self.state_path = Path(state_path) if state_path else STATE_PATH
+
+    def load(self) -> Dict[str, Any]:
+        if not self.state_path.exists():
+            return {}
+        try:
+            with open(self.state_path, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+    def save(self, state: Dict[str, Any]) -> None:
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.state_path, "w") as f:
+            json.dump(state, f, indent=2)
+            f.write("\n")
+
+    def save_role(self, role: str, role_state: Dict[str, Any]) -> None:
+        state = self.load()
+        state[role] = role_state
+        self.save(state)
+
+    def remove_role(self, role: str) -> None:
+        state = self.load()
+        state.pop(role, None)
+        self.save(state)
+
+    def get_role(self, role: str) -> Optional[Dict[str, Any]]:
+        state = self.load()
+        return state.get(role)
+
+    def cleanup_stale(self) -> List[str]:
+        """Remove entries for processes that are no longer running. Returns cleaned role names."""
+        state = self.load()
+        cleaned = []
+        for role, info in list(state.items()):
+            pid = info.get("pid")
+            if pid and not is_process_running(pid):
+                del state[role]
+                cleaned.append(role)
+        if cleaned:
+            self.save(state)
+        return cleaned
+
+
+class ServerManager:
+    """Manages starting, stopping, and checking LLM inference servers."""
+
+    HOST = "127.0.0.1"
+    STARTUP_TIMEOUT = 60  # seconds to wait for server to be ready
+
+    def __init__(self, state_file: Optional[StateFile] = None):
+        self.state = state_file or StateFile()
+
+    @staticmethod
+    def _build_mlx_command(model_path: str, host: str, port: int) -> List[str]:
+        """Build the command to start an MLX model server."""
+        return [
+            "mlx_lm", "serve", model_path,
+            "--host", host,
+            "--port", str(port),
+        ]
+
+    @staticmethod
+    def _build_gguf_command(model_path: str, host: str, port: int) -> List[str]:
+        """Build the command to start a GGUF model server via llama-server."""
+        return [
+            "llama-server",
+            "--model", model_path,
+            "--host", host,
+            "--port", str(port),
+        ]
+
+    def start(self, role: str, role_config: Dict[str, Any]) -> Dict[str, Any]:
+        """Start the server for a given role.
+
+        Returns the role state info.
+        """
+        # Check if already running
+        existing = self.state.get_role(role)
+        if existing and is_process_running(existing.get("pid", 0)):
+            return existing
+
+        # Clean up stale entry if exists
+        if existing:
+            self.state.remove_role(role)
+
+        model_type = role_config.get("type", "mlx")
+        model_path = role_config.get("path", "")
+        port = role_config.get("port", 8080)
+
+        if model_type == "mlx":
+            cmd = self._build_mlx_command(model_path, self.HOST, port)
+        elif model_type == "gguf":
+            cmd = self._build_gguf_command(model_path, self.HOST, port)
+        else:
+            raise ValueError(f"Unsupported model type: {model_type}")
+
+        # Check that the command exists
+        cmd_name = cmd[0]
+        if not self._command_exists(cmd_name):
+            raise RuntimeError(
+                f"Command '{cmd_name}' not found in PATH. "
+                f"Make sure {'mlx_lm' if model_type == 'mlx' else 'llama.cpp'} is installed."
+            )
+
+        # Start the process
+        # Redirect output to log file
+        log_dir = Path.home() / ".config" / "llm-ctl" / "logs"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_file = log_dir / f"{role}.log"
+
+        # Open log file — do NOT use a context manager. The child process inherits
+        # the file descriptor, and closing it would send SIGPIPE to the child,
+        # killing the server before it finishes starting.
+        log_fh = open(log_file, "w")
+        process = subprocess.Popen(
+            cmd,
+            stdout=log_fh,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+        # log_fh is intentionally left open — the OS will clean up the fd when
+        # both the parent (this Python process) and child (the server) exit.
+
+        # Wait for server to be ready
+        ready = wait_for_port_ready(port, self.HOST, timeout=self.STARTUP_TIMEOUT)
+        if not ready:
+            # Server didn't start in time — kill it
+            try:
+                os.kill(process.pid, signal.SIGTERM)
+            except OSError:
+                pass
+            raise RuntimeError(
+                f"Server for role '{role}' failed to start within {self.STARTUP_TIMEOUT}s. "
+                f"Check {log_file} for details."
+            )
+
+        role_state = {
+            "pid": process.pid,
+            "port": port,
+            "command": " ".join(cmd),
+            "started_at": datetime.now(timezone.utc).isoformat(),
+            "log_file": str(log_file),
+        }
+        self.state.save_role(role, role_state)
+        return role_state
+
+    def stop(self, role: str) -> bool:
+        """Stop the server for a given role. Returns True if a server was stopped."""
+        role_state = self.state.get_role(role)
+        if not role_state:
+            return False
+
+        pid = role_state.get("pid")
+        if pid and is_process_running(pid):
+            try:
+                os.kill(pid, signal.SIGTERM)
+                # Wait up to 10 seconds for graceful shutdown
+                for _ in range(20):
+                    if not is_process_running(pid):
+                        break
+                    time.sleep(0.5)
+                # Force kill if still running
+                if is_process_running(pid):
+                    os.kill(pid, signal.SIGKILL)
+            except OSError:
+                pass
+
+        self.state.remove_role(role)
+        return True
+
+    def status(self, role: str) -> Dict[str, Any]:
+        """Get the status of a server for a given role."""
+        role_state = self.state.get_role(role)
+        if not role_state:
+            return {
+                "role": role,
+                "running": False,
+                "pid": None,
+                "port": None,
+            }
+
+        pid = role_state.get("pid")
+        running = is_process_running(pid) if pid else False
+
+        return {
+            "role": role,
+            "running": running,
+            "pid": pid,
+            "port": role_state.get("port"),
+            "started_at": role_state.get("started_at"),
+            "command": role_state.get("command"),
+        }
+
+    def start_all(self) -> List[Dict[str, Any]]:
+        """Start servers for all registered roles."""
+        config = ConfigManager()
+        roles = config.get_all_roles()
+        results = []
+        for role, role_config in roles.items():
+            try:
+                state = self.start(role, role_config)
+                results.append({"role": role, "status": "started", "info": state})
+            except Exception as e:
+                results.append({"role": role, "status": "error", "error": str(e)})
+        return results
+
+    def stop_all(self) -> List[Dict[str, Any]]:
+        """Stop all running servers."""
+        config = ConfigManager()
+        roles = config.get_all_roles()
+        results = []
+        for role in roles:
+            try:
+                stopped = self.stop(role)
+                results.append({"role": role, "status": "stopped" if stopped else "not running"})
+            except Exception as e:
+                results.append({"role": role, "status": "error", "error": str(e)})
+        return results
+
+    def get_all_status(self) -> List[Dict[str, Any]]:
+        """Get status of all registered role servers."""
+        # Clean up stale entries first
+        self.state.cleanup_stale()
+
+        config = ConfigManager()
+        roles = config.get_all_roles()
+        status_list = []
+        for role, role_config in roles.items():
+            status = self.status(role)
+            status["model_id"] = role_config.get("model_id", "unknown")
+            status["type"] = role_config.get("type", "unknown")
+            status_list.append(status)
+        return status_list
+
+    @staticmethod
+    def _command_exists(cmd: str) -> bool:
+        """Check if a command exists in PATH."""
+        import shutil
+        return shutil.which(cmd) is not None

llm_ctl/utils.py

@@ -0,0 +1,68 @@
+"""Utility functions for llm-ctl."""
+
+import os
+import signal
+import socket
+import time
+from pathlib import Path
+from typing import Optional, Set
+
+
+def expand_path(path_str: str) -> str:
+    """Expand ~ and environment variables in a path string."""
+    return os.path.expandvars(os.path.expanduser(path_str))
+
+
+def is_process_running(pid: int) -> bool:
+    """Check if a process with the given PID is running."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def is_port_available(port: int, host: str = "127.0.0.1") -> bool:
+    """Check if a TCP port is available (not in use)."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def find_next_available_port(start: int = 8080, host: str = "127.0.0.1", max_attempts: int = 100, exclude: Optional[Set[int]] = None) -> int:
+    """Find the next available port starting from the given port.
+    
+    Args:
+        start: First port to try.
+        host: Host to bind against for availability check.
+        max_attempts: Maximum number of ports to try.
+        exclude: Set of port numbers to skip even if available (e.g., already assigned to other roles).
+    """
+    if exclude is None:
+        exclude = set()
+    for port in range(start, start + max_attempts):
+        if port in exclude:
+            continue
+        if is_port_available(port, host):
+            return port
+    raise RuntimeError(f"No available port found in range {start}-{start + max_attempts}")
+
+
+def wait_for_port_ready(port: int, host: str = "127.0.0.1", timeout: int = 30, interval: float = 0.5) -> bool:
+    """Wait for a port to become reachable (server is listening). Returns True if the port accepts connections.
+    
+    This checks whether something is actively listening on the port — the opposite of
+    is_port_available(), which checks whether a port is free to bind.
+    """
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.settimeout(1)
+            result = s.connect_ex((host, port))
+            if result == 0:
+                return True
+        time.sleep(interval)
+    return False

local_llm_ctl-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: local-llm-ctl
+Version: 0.1.0
+Summary: CLI tool to manage local LLM models and role-based server lifecycle
+Author: Renato Rozas
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: huggingface-hub>=0.20

local_llm_ctl-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+llm_ctl/__init__.py,sha256=xzx3cLsIxXqVDud175hlXASsCz3P9Y4OMUmOHb61yaA,75
+llm_ctl/__main__.py,sha256=W7V4Qx4-94fFwoGz-6BTIsCkRb61umaHG7JVMK7BveY,66
+llm_ctl/cli.py,sha256=IA33ZH1vrKMUd59Tx5EzBtrs4PrXRoqkeqGyTzC2yTo,9824
+llm_ctl/config.py,sha256=9BDgL8zqn4fOQ-WXcs_sPidfNeIYVZfPG5mipFvrF8s,2628
+llm_ctl/models.py,sha256=5XvHDmTAYtZo4HZeQ8CtgVDA0MU9j_fMI2E352tSIyk,7556
+llm_ctl/server.py,sha256=A24dg5frSs_Lv2LgK9dJfp8oV89hN4U1JHy73U5d1vc,9097
+llm_ctl/utils.py,sha256=Ukq3x-W4RaEHxQBgR72B5fqFiVzoxPAVAR82jSBF9bg,2344
+local_llm_ctl-0.1.0.dist-info/METADATA,sha256=vNBonm1ID7-fwqWDvTVYY7Hi6U8rTwJr4shy2EjaTeU,265
+local_llm_ctl-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+local_llm_ctl-0.1.0.dist-info/entry_points.txt,sha256=L0XwIOEPQgVV9ZP1_F8YSLwTP9ojQOvRkVGoW9tcvw0,44
+local_llm_ctl-0.1.0.dist-info/top_level.txt,sha256=ZbmQR11Vu7Fb8ywia7XEIo0wmA_81Dxm4N4m2Ly4eZs,8
+local_llm_ctl-0.1.0.dist-info/RECORD,,

local_llm_ctl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

local_llm_ctl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+llm-ctl = llm_ctl.cli:cli

local_llm_ctl-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llm_ctl