opencode-llama-cpp-launcher 0.1.0__py3-none-any.whl

opencode_llama_cpp_launcher/__init__.py

@@ -0,0 +1,3 @@
+"""OpenCode llama.cpp launcher package."""
+
+__version__ = "0.1.0"

opencode_llama_cpp_launcher/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entrypoints."""

opencode_llama_cpp_launcher/cli/entrypoint.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from opencode_llama_cpp_launcher.services.binaries import require_binary
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+from opencode_llama_cpp_launcher.services.launch_config_loader import LaunchConfigLoader
+from opencode_llama_cpp_launcher.services.launcher import Launcher
+
+
+app = typer.Typer(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+    no_args_is_help=False,
+    help="Launch OpenCode against a local llama.cpp GGUF model.",
+)
+
+
+@app.callback()
+def launch_callback(
+    ctx: typer.Context,
+    model: Path | None = typer.Option(
+        None,
+        "--model",
+        "-m",
+        help="GGUF model path. Overrides YAML config.",
+    ),
+    llama_server: Path | None = typer.Option(
+        None,
+        "--llama-server",
+        help="llama-server binary path. Overrides YAML config and PATH lookup.",
+    ),
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project directory where OpenCode should run.",
+    ),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        "-f",
+        help="Path to opencode-llama.yaml.",
+    ),
+    port: int | None = typer.Option(
+        None,
+        "--port",
+        help="Preferred llama-server port.",
+    ),
+    ctx_size: int | None = typer.Option(
+        None,
+        "--ctx-size",
+        help="llama-server context size.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print resolved commands and generated config without launching.",
+    ),
+) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+
+    try:
+        launch_config = LaunchConfigLoader().load(
+            model=model,
+            llama_server=llama_server,
+            project=project,
+            config=config,
+            port=port,
+            ctx_size=ctx_size,
+            dry_run=dry_run,
+        )
+        raise typer.Exit(_shell_exit_code(Launcher().run(launch_config)))
+    except LauncherError as exc:
+        _print_error(str(exc))
+        raise typer.Exit(1) from exc
+
+
+@app.command()
+def doctor() -> None:
+    """Check whether required external binaries are available."""
+    failed = False
+
+    for binary_name in ("llama-server", "opencode"):
+        try:
+            binary_path = require_binary(binary_name)
+            typer.echo(f"OK {binary_name}: {binary_path}")
+        except LauncherError as exc:
+            failed = True
+            typer.echo(f"Missing {binary_name}: {exc}", err=True)
+
+    if failed:
+        raise typer.Exit(1)
+
+
+def _print_error(message: str) -> None:
+    typer.echo(f"Error: {message}", err=True)
+
+
+def _shell_exit_code(return_code: int) -> int:
+    if return_code >= 0:
+        return return_code
+    return 128 + abs(return_code)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

opencode_llama_cpp_launcher/models/__init__.py

@@ -0,0 +1 @@
+"""Data models for launcher configuration and status."""

opencode_llama_cpp_launcher/models/launch_config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8080
+MAX_PORT = 65535
+DEFAULT_CTX_SIZE = 8192
+
+
+@dataclass(frozen=True)
+class LaunchConfig:
+    project: Path
+    model_path: Path
+    llama_server_path: Path | None = None
+    port: int = DEFAULT_PORT
+    ctx_size: int = DEFAULT_CTX_SIZE
+    host: str = DEFAULT_HOST
+    dry_run: bool = False
+
+
+@dataclass(frozen=True)
+class LlamaServerConfig:
+    model_path: Path
+    command: list[str]
+    selected_port: int
+    root_url: str
+    base_url: str
+
+
+@dataclass(frozen=True)
+class OpenCodeConfig:
+    command: list[str]
+    config: dict
+
+
+@dataclass(frozen=True)
+class BuiltLaunchConfig:
+    project: Path
+    llama_server: LlamaServerConfig
+    opencode: OpenCodeConfig

opencode_llama_cpp_launcher/models/launch_status.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class LaunchStatus(StrEnum):
+    IDLE = "Idle"
+    CHECKING_PREREQUISITES = "Checking prerequisites"
+    STARTING_LLAMA_SERVER = "Starting llama-server"
+    WAITING_FOR_LLAMA_SERVER = "Waiting for llama-server"
+    DETECTING_MODEL = "Detecting model"
+    STARTING_OPENCODE = "Starting OpenCode"
+    READY = "Ready"
+    ERROR = "Error"

opencode_llama_cpp_launcher/services/__init__.py

@@ -0,0 +1 @@
+"""Launcher services."""

opencode_llama_cpp_launcher/services/binaries.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import shutil
+
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+
+
+def require_binary(name: str) -> str:
+    binary_path = shutil.which(name)
+    if binary_path is None:
+        raise LauncherError(f"`{name}` was not found in PATH.")
+    return binary_path

opencode_llama_cpp_launcher/services/errors.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class LauncherError(RuntimeError):
+    """Expected user-facing launcher failure."""

opencode_llama_cpp_launcher/services/health.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+
+
+def wait_for_health(
+    root_url: str,
+    timeout_seconds: float = 120.0,
+    interval_seconds: float = 0.5,
+    is_server_running: Callable[[], bool] | None = None,
+) -> None:
+    deadline = time.monotonic() + timeout_seconds
+    last_error: Exception | None = None
+
+    while time.monotonic() < deadline:
+        if is_server_running is not None and not is_server_running():
+            raise LauncherError("llama-server exited before becoming ready.")
+
+        try:
+            with urllib.request.urlopen(f"{root_url}/health", timeout=2.0) as response:
+                if response.status == 200:
+                    return
+        except OSError as exc:
+            last_error = exc
+
+        if is_server_running is not None and not is_server_running():
+            raise LauncherError("llama-server exited before becoming ready.")
+
+        time.sleep(interval_seconds)
+
+    suffix = f" Last error: {last_error}" if last_error else ""
+    raise LauncherError(f"llama-server did not become ready at {root_url}.{suffix}")
+
+
+def fetch_first_model_id(base_url: str) -> str:
+    try:
+        with urllib.request.urlopen(f"{base_url}/models", timeout=5.0) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise LauncherError(f"Could not query llama-server models: {exc}") from exc
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise LauncherError("llama-server returned invalid JSON from /v1/models.") from exc
+
+    data = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(data, list) or not data:
+        raise LauncherError("No models returned from llama-server /v1/models.")
+
+    first_model = data[0]
+    model_id = first_model.get("id") if isinstance(first_model, dict) else None
+    if not isinstance(model_id, str) or not model_id:
+        raise LauncherError("First llama-server model entry did not include an id.")
+
+    return model_id

opencode_llama_cpp_launcher/services/launch_config_loader.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from opencode_llama_cpp_launcher.models.launch_config import LaunchConfig, MAX_PORT
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+from opencode_llama_cpp_launcher.storage.config_loader import (
+    CONFIG_TEMPLATE,
+    FileConfig,
+    load_file_config,
+)
+
+
+class LaunchConfigLoader:
+    """Merge CLI options and YAML defaults into the launch request."""
+
+    def load(
+        self,
+        *,
+        model: Path | None,
+        llama_server: Path | None,
+        project: Path,
+        config: Path | None,
+        port: int | None,
+        ctx_size: int | None,
+        dry_run: bool,
+    ) -> LaunchConfig:
+        project_path = self._absolute_path(project)
+        file_config = load_file_config(project_path, config)
+
+        # CLI flags should always win over values remembered in the project file.
+        model_path = self._model_path_from_cli_or_config(model, file_config)
+        llama_server_path = self._llama_server_path_from_cli_or_config(
+            llama_server,
+            file_config,
+        )
+        selected_port = self._port_from_cli_or_config(port, file_config)
+        selected_ctx_size = self._ctx_size_from_cli_or_config(ctx_size, file_config)
+
+        if model_path is None:
+            self._raise_missing_model()
+
+        self._validate_port(selected_port)
+        self._validate_ctx_size(selected_ctx_size)
+
+        return LaunchConfig(
+            project=project_path,
+            model_path=model_path,
+            llama_server_path=llama_server_path,
+            port=selected_port,
+            ctx_size=selected_ctx_size,
+            dry_run=dry_run,
+        )
+
+    def _model_path_from_cli_or_config(
+        self,
+        model: Path | None,
+        file_config: FileConfig,
+    ) -> Path | None:
+        if model is not None:
+            return self._absolute_path(model)
+        if file_config.model is not None:
+            return self._absolute_path(file_config.model)
+        return None
+
+    def _llama_server_path_from_cli_or_config(
+        self,
+        llama_server: Path | None,
+        file_config: FileConfig,
+    ) -> Path | None:
+        if llama_server is not None:
+            return self._absolute_path(llama_server)
+        if file_config.llama_server_path is not None:
+            return self._absolute_path(file_config.llama_server_path)
+        return None
+
+    def _port_from_cli_or_config(self, port: int | None, file_config: FileConfig) -> int:
+        return port if port is not None else file_config.port
+
+    def _ctx_size_from_cli_or_config(
+        self,
+        ctx_size: int | None,
+        file_config: FileConfig,
+    ) -> int:
+        return ctx_size if ctx_size is not None else file_config.ctx_size
+
+    def _validate_port(self, port: int) -> None:
+        if not 0 < port <= MAX_PORT:
+            raise LauncherError(f"Port must be between 1 and {MAX_PORT}.")
+
+    def _validate_ctx_size(self, ctx_size: int) -> None:
+        if ctx_size <= 0:
+            raise LauncherError("Context size must be greater than zero.")
+
+    def _raise_missing_model(self) -> None:
+        raise LauncherError(
+            "No GGUF model path was provided.\n\n"
+            "Pass one with `--model /absolute/path/to/model.gguf` or create:\n\n"
+            f"{CONFIG_TEMPLATE}"
+        )
+
+    def _absolute_path(self, path: Path) -> Path:
+        # Normalize paths once at the boundary so downstream services can compare
+        # and execute them without repeating expanduser/relative-path handling.
+        return path.expanduser().resolve()

opencode_llama_cpp_launcher/services/launch_preparer.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from opencode_llama_cpp_launcher.models.launch_config import (
+    LaunchConfig,
+    BuiltLaunchConfig,
+    LlamaServerConfig,
+    OpenCodeConfig,
+)
+from opencode_llama_cpp_launcher.services.binaries import require_binary
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+from opencode_llama_cpp_launcher.services.opencode_config import (
+    build_opencode_config as build_opencode_provider_config,
+)
+from opencode_llama_cpp_launcher.services.ports import select_port
+
+
+@dataclass(frozen=True)
+class ServerUrls:
+    root: str
+    base: str
+
+
+class LaunchPreparer:
+    """Turn the launch request into commands, URLs, and provider config."""
+
+    def prepare(self, config: LaunchConfig) -> BuiltLaunchConfig:
+        self._validate_launch_targets(config)
+
+        llama_server_binary = self._llama_server_binary(config)
+        opencode_binary = require_binary("opencode")
+        selected_port = select_port(config.host, config.port)
+        urls = self._server_urls(config.host, selected_port)
+
+        return BuiltLaunchConfig(
+            project=config.project,
+            llama_server=self._build_llama_server_config(
+                config=config,
+                llama_server_binary=llama_server_binary,
+                selected_port=selected_port,
+                urls=urls,
+            ),
+            opencode=self._build_opencode_config(
+                opencode_binary=opencode_binary,
+                base_url=urls.base,
+                model_id=config.model_path.stem,
+            ),
+        )
+
+    def _build_llama_server_config(
+        self,
+        *,
+        config: LaunchConfig,
+        llama_server_binary: str,
+        selected_port: int,
+        urls: ServerUrls,
+    ) -> LlamaServerConfig:
+        return LlamaServerConfig(
+            model_path=config.model_path,
+            command=self._llama_server_command(
+                llama_server_binary=llama_server_binary,
+                config=config,
+                selected_port=selected_port,
+            ),
+            selected_port=selected_port,
+            root_url=urls.root,
+            base_url=urls.base,
+        )
+
+    def _build_opencode_config(
+        self,
+        *,
+        opencode_binary: str,
+        base_url: str,
+        model_id: str,
+    ) -> OpenCodeConfig:
+        return OpenCodeConfig(
+            command=[opencode_binary],
+            config=build_opencode_provider_config(base_url, model_id),
+        )
+
+    def _llama_server_binary(self, config: LaunchConfig) -> str:
+        if config.llama_server_path is None:
+            return require_binary("llama-server")
+
+        # A configured binary path is intentional, so fail clearly instead of
+        # silently falling back to a different llama-server on PATH.
+        return self._checked_binary_path("llama-server", config.llama_server_path)
+
+    def _checked_binary_path(self, name: str, path: Path) -> str:
+        if not path.exists() or not path.is_file():
+            raise LauncherError(f"`{name}` binary does not exist: {path}")
+        if not os.access(path, os.X_OK):
+            raise LauncherError(f"`{name}` binary is not executable: {path}")
+
+        return str(path)
+
+    def _validate_launch_targets(self, config: LaunchConfig) -> None:
+        if not config.project.exists() or not config.project.is_dir():
+            raise LauncherError(f"Project directory does not exist: {config.project}")
+        if not config.model_path.exists() or not config.model_path.is_file():
+            raise LauncherError(
+                f"Selected GGUF file does not exist: {config.model_path}"
+            )
+
+    def _llama_server_command(
+        self,
+        llama_server_binary: str,
+        config: LaunchConfig,
+        selected_port: int,
+    ) -> list[str]:
+        return [
+            llama_server_binary,
+            "-m",
+            str(config.model_path),
+            "--host",
+            config.host,
+            "--port",
+            str(selected_port),
+            "-c",
+            str(config.ctx_size),
+        ]
+
+    def _server_urls(self, host: str, port: int) -> ServerUrls:
+        root_url = f"http://{host}:{port}"
+        # llama-server's OpenAI-compatible routes live under /v1.
+        return ServerUrls(root=root_url, base=f"{root_url}/v1")

opencode_llama_cpp_launcher/services/launcher.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import tempfile
+from collections.abc import Callable
+from typing import BinaryIO
+
+from opencode_llama_cpp_launcher.models.launch_config import (
+    BuiltLaunchConfig,
+    LaunchConfig,
+)
+from opencode_llama_cpp_launcher.models.launch_status import LaunchStatus
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+from opencode_llama_cpp_launcher.services.health import fetch_first_model_id, wait_for_health
+from opencode_llama_cpp_launcher.services.launch_preparer import LaunchPreparer
+from opencode_llama_cpp_launcher.services.opencode_config import (
+    build_opencode_config,
+    dumps_opencode_config,
+)
+
+
+StatusReporter = Callable[[LaunchStatus], None]
+LLAMA_SERVER_LOG_TAIL_BYTES = 4000
+
+
+def default_reporter(status: LaunchStatus) -> None:
+    print(status.value, flush=True)
+
+
+class Launcher:
+    def __init__(
+        self,
+        report_status: StatusReporter = default_reporter,
+        launch_preparer: LaunchPreparer | None = None,
+    ) -> None:
+        self._report_status = report_status
+        self._launch_preparer = launch_preparer or LaunchPreparer()
+
+    def run(self, config: LaunchConfig) -> int:
+        built_config = self._build_config(config)
+
+        if config.dry_run:
+            self._print_dry_run(built_config)
+            return 0
+
+        with tempfile.TemporaryFile("w+b") as llama_server_log:
+            llama_process = self._start_llama_server(built_config, llama_server_log)
+            try:
+                try:
+                    self._wait_for_llama_server(
+                        built_config.llama_server.root_url,
+                        llama_process,
+                    )
+                except LauncherError as exc:
+                    self._raise_with_llama_server_log(exc, llama_server_log)
+
+                # The real model id is only available after llama-server starts.
+                opencode_config = self._detect_opencode_config(
+                    built_config.llama_server.base_url,
+                )
+                opencode_process = self._start_opencode(
+                    built_config,
+                    opencode_config,
+                )
+                return int(opencode_process.wait())
+            finally:
+                # OpenCode owns the interactive session; this launcher owns cleanup
+                # for the llama-server process it started.
+                self._terminate_process(llama_process)
+
+    def _build_config(self, config: LaunchConfig) -> BuiltLaunchConfig:
+        self._report_status(LaunchStatus.CHECKING_PREREQUISITES)
+        return self._launch_preparer.prepare(config)
+
+    def _start_llama_server(
+        self,
+        config: BuiltLaunchConfig,
+        log_file: BinaryIO,
+    ) -> subprocess.Popen:
+        self._report_status(LaunchStatus.STARTING_LLAMA_SERVER)
+        # Keep llama-server isolated from OpenCode's terminal UI and make the
+        # whole llama.cpp process group easy to stop when OpenCode exits.
+        popen_kwargs = {
+            "stdin": subprocess.DEVNULL,
+            "stdout": log_file,
+            "stderr": subprocess.STDOUT,
+        }
+        if hasattr(os, "setsid"):
+            popen_kwargs["start_new_session"] = True
+
+        return subprocess.Popen(config.llama_server.command, **popen_kwargs)
+
+    def _wait_for_llama_server(
+        self,
+        root_url: str,
+        process: subprocess.Popen,
+    ) -> None:
+        self._report_status(LaunchStatus.WAITING_FOR_LLAMA_SERVER)
+        wait_for_health(
+            root_url,
+            is_server_running=lambda: process.poll() is None,
+        )
+
+    def _detect_opencode_config(self, base_url: str) -> dict:
+        self._report_status(LaunchStatus.DETECTING_MODEL)
+        model_id = fetch_first_model_id(base_url)
+        return build_opencode_config(base_url, model_id)
+
+    def _start_opencode(
+        self,
+        built_config: BuiltLaunchConfig,
+        opencode_config: dict,
+    ) -> subprocess.Popen:
+        self._report_status(LaunchStatus.STARTING_OPENCODE)
+        return subprocess.Popen(
+            built_config.opencode.command,
+            cwd=built_config.project,
+            env=self._opencode_env(opencode_config),
+        )
+
+    def _opencode_env(self, opencode_config: dict) -> dict[str, str]:
+        env = os.environ.copy()
+        env["OPENCODE_CONFIG_CONTENT"] = dumps_opencode_config(opencode_config)
+        return env
+
+    def _print_dry_run(self, config: BuiltLaunchConfig) -> None:
+        print(f"Project: {config.project}")
+        print(f"Model: {config.llama_server.model_path}")
+        print(f"Selected port: {config.llama_server.selected_port}")
+        print("llama-server command:")
+        print(" ".join(config.llama_server.command))
+        print("opencode command:")
+        print(" ".join(config.opencode.command))
+        print("OPENCODE_CONFIG_CONTENT:")
+        print(dumps_opencode_config(config.opencode.config))
+
+    def _raise_with_llama_server_log(
+        self,
+        exc: LauncherError,
+        log_file: BinaryIO,
+    ) -> None:
+        log_excerpt = self._llama_server_log_excerpt(log_file)
+        if not log_excerpt:
+            raise exc
+
+        raise LauncherError(f"{exc}\n\nllama-server output:\n{log_excerpt}") from exc
+
+    def _llama_server_log_excerpt(self, log_file: BinaryIO) -> str:
+        log_file.flush()
+        log_file.seek(0, os.SEEK_END)
+        size = log_file.tell()
+        if size == 0:
+            return ""
+
+        offset = max(0, size - LLAMA_SERVER_LOG_TAIL_BYTES)
+        log_file.seek(offset)
+        excerpt = log_file.read().decode("utf-8", errors="replace")
+        if offset > 0:
+            return f"[last {LLAMA_SERVER_LOG_TAIL_BYTES} bytes]\n{excerpt}"
+        return excerpt
+
+    def _terminate_process(self, process: subprocess.Popen) -> None:
+        if process.poll() is not None:
+            return
+
+        self._terminate_process_group(process)
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self._kill_process_group(process)
+            process.wait()
+
+    def _terminate_process_group(self, process: subprocess.Popen) -> None:
+        if not hasattr(os, "killpg"):
+            process.terminate()
+            return
+
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+        except ProcessLookupError:
+            return
+        except OSError:
+            process.terminate()
+
+    def _kill_process_group(self, process: subprocess.Popen) -> None:
+        if not hasattr(os, "killpg"):
+            process.kill()
+            return
+
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            return
+        except OSError:
+            process.kill()

opencode_llama_cpp_launcher/services/opencode_config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+
+
+PROVIDER_ID = "llama.cpp"
+PROVIDER_PACKAGE = "@ai-sdk/openai-compatible"
+
+
+def build_opencode_config(base_url: str, model_id: str) -> dict:
+    selected_model = f"{PROVIDER_ID}/{model_id}"
+    return {
+        "$schema": "https://opencode.ai/config.json",
+        "model": selected_model,
+        "small_model": selected_model,
+        "provider": {
+            PROVIDER_ID: {
+                "npm": PROVIDER_PACKAGE,
+                "name": "llama-server (local)",
+                "options": {
+                    "baseURL": base_url,
+                },
+                "models": {
+                    model_id: {
+                        "name": f"{model_id} (local)",
+                    },
+                },
+            },
+        },
+    }
+
+
+def dumps_opencode_config(config: dict) -> str:
+    return json.dumps(config, separators=(",", ":"))

opencode_llama_cpp_launcher/services/ports.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import socket
+
+
+def select_port(host: str, preferred_port: int) -> int:
+    if is_port_available(host, preferred_port):
+        return preferred_port
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind((host, 0))
+        return int(sock.getsockname()[1])
+
+
+def is_port_available(host: str, port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(0.2)
+        return sock.connect_ex((host, port)) != 0

opencode_llama_cpp_launcher/storage/__init__.py

@@ -0,0 +1 @@
+"""Config loading and storage helpers."""

opencode_llama_cpp_launcher/storage/config_loader.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from opencode_llama_cpp_launcher.models.launch_config import (
+    DEFAULT_CTX_SIZE,
+    DEFAULT_PORT,
+    MAX_PORT,
+)
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+
+
+DEFAULT_CONFIG_NAMES = (
+    "opencode-llama.yaml",
+    "opencode-llama.yml",
+    ".opencode-llama.yaml",
+    ".opencode-llama.yml",
+)
+XDG_CONFIG_HOME_ENV = "XDG_CONFIG_HOME"
+USER_CONFIG_NAMES = ("opencode-llama.yaml", ".opencode-llama.yaml")
+
+CONFIG_TEMPLATE = """# opencode-llama.yaml or ~/.config/opencode-llama.yaml
+model: /absolute/path/to/model.gguf
+llama_server: /optional/path/to/llama-server
+port: 8080
+ctx_size: 8192
+"""
+
+
+@dataclass(frozen=True)
+class FileConfig:
+    path: Path | None
+    model: Path | None = None
+    llama_server_path: Path | None = None
+    port: int = DEFAULT_PORT
+    ctx_size: int = DEFAULT_CTX_SIZE
+
+
+def find_config_path(project: Path, explicit_config: Path | None) -> Path | None:
+    if explicit_config is not None:
+        return explicit_config.expanduser()
+
+    for config_name in DEFAULT_CONFIG_NAMES:
+        candidate = project / config_name
+        if candidate.exists():
+            return candidate
+
+    for config_path in get_user_config_paths():
+        if config_path.exists():
+            return config_path
+
+    return None
+
+
+def get_user_config_paths() -> tuple[Path, Path]:
+    config_home = os.environ.get(XDG_CONFIG_HOME_ENV)
+    if config_home:
+        config_dir = Path(config_home).expanduser()
+    else:
+        config_dir = Path.home() / ".config"
+
+    preferred_config_name, dotted_config_name = USER_CONFIG_NAMES
+    return (
+        config_dir / preferred_config_name,
+        config_dir / dotted_config_name,
+    )
+
+
+def load_file_config(project: Path, explicit_config: Path | None = None) -> FileConfig:
+    config_path = find_config_path(project, explicit_config)
+    if config_path is None:
+        return FileConfig(path=None)
+
+    if not config_path.exists():
+        raise LauncherError(f"Config file does not exist: {config_path}")
+
+    raw_config = _load_yaml_mapping(config_path)
+    return FileConfig(
+        path=config_path,
+        model=_path_value(raw_config.get("model"), config_path.parent, "model"),
+        llama_server_path=_path_value(
+            raw_config.get("llama_server"),
+            config_path.parent,
+            "llama_server",
+        ),
+        port=_int_value(raw_config.get("port"), DEFAULT_PORT, "port"),
+        ctx_size=_int_value(raw_config.get("ctx_size"), DEFAULT_CTX_SIZE, "ctx_size"),
+    )
+
+
+def _load_yaml_mapping(config_path: Path) -> dict[str, Any]:
+    try:
+        raw_config = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise LauncherError(f"Could not parse YAML config {config_path}: {exc}") from exc
+    except OSError as exc:
+        raise LauncherError(f"Could not read config {config_path}: {exc}") from exc
+
+    if raw_config is None:
+        return {}
+
+    if not isinstance(raw_config, dict):
+        raise LauncherError(f"Config file must contain a YAML mapping: {config_path}")
+
+    return raw_config
+
+
+def _path_value(value: Any, base_dir: Path, key: str) -> Path | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise LauncherError(f"Config value `{key}` must be a string path.")
+
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        path = base_dir / path
+    return path
+
+
+def _int_value(value: Any, default: int, key: str) -> int:
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise LauncherError(f"Config value `{key}` must be an integer.")
+    if value <= 0:
+        raise LauncherError(f"Config value `{key}` must be greater than zero.")
+    if key == "port" and value > MAX_PORT:
+        raise LauncherError(f"Config value `{key}` must be at most {MAX_PORT}.")
+    return value

opencode_llama_cpp_launcher-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: opencode-llama-cpp-launcher
+Version: 0.1.0
+Summary: One command launcher for running OpenCode with a local llama.cpp model.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic-coding,cli,llama-cpp,local-llm,opencode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# OpenCode llama.cpp Launcher
+
+A one command solution for launching [OpenCode](https://opencode.ai/) with any
+local LLM that `llama-server` can serve, including models like Qwen, DeepSeek,
+and Gemma. This launcher starts `llama-server`, waits for it to become ready,
+wires the OpenAI compatible provider config into OpenCode, and cleans up when
+the local agentic coding session ends.
+
+## Requirements
+
+- Python 3.12+
+- OpenCode
+- llama.cpp's `llama-server`
+- A local model supported by `llama-server`, for example Qwen, DeepSeek, or
+  Gemma
+
+The launcher finds `llama-server` on `PATH`, or you can set `llama_server` in
+your config.
+
+## Install
+
+From this repository:
+
+```bash
+uv sync --dev
+```
+
+Check that the required external binaries are available:
+
+```bash
+uv run opencode-llama doctor
+```
+
+## Configure
+
+Create a project-local config in the project where you want OpenCode to run:
+
+```bash
+cp opencode-llama.example.yaml opencode-llama.yaml
+```
+
+Then edit `opencode-llama.yaml`:
+
+```yaml
+model: /absolute/path/to/model.gguf
+llama_server: /optional/path/to/llama-server
+port: 8080
+ctx_size: 8192
+```
+
+Config lookup order:
+
+1. The path passed with `--config`
+2. `opencode-llama.yaml` or `opencode-llama.yml` in the project directory
+3. `~/.config/opencode-llama.yaml`
+
+## Usage
+
+Run with an explicit config file:
+
+```bash
+uv run opencode-llama --config opencode-llama.yaml
+```
+
+Or pass the model directly:
+
+```bash
+uv run opencode-llama --model /absolute/path/to/model.gguf
+```
+
+Useful options:
+
+```bash
+uv run opencode-llama --help
+uv run opencode-llama --dry-run
+uv run opencode-llama --config opencode-llama.yaml
+uv run opencode-llama --port 9001
+uv run opencode-llama --ctx-size 8192
+uv run opencode-llama --llama-server /absolute/path/to/llama-server
+```
+
+If `llama-server` fails before becoming healthy, the launcher includes a bounded
+tail of the server's startup output in the error message. Successful runs stay
+quiet.
+
+## Development
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Before publishing, check for local files:
+
+```bash
+git status --short --ignored
+```
+
+Do not commit local launcher configs, virtual environments, caches, build
+artifacts, or model paths.
+
+## License
+
+MIT

opencode_llama_cpp_launcher-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+opencode_llama_cpp_launcher/__init__.py,sha256=PCZOkVwXXSr3RYPNZdZz-2Qo-6vATkk68dDCW0FJeiI,66
+opencode_llama_cpp_launcher/cli/__init__.py,sha256=p3sRYNlgLcYI08JgetCyqf1wpgvZlRBdz_R6MbxU_cI,23
+opencode_llama_cpp_launcher/cli/entrypoint.py,sha256=OkKMhTXg1mp2AxnwwM2H0GNy739RewgnPXAHb_MwK9U,2963
+opencode_llama_cpp_launcher/models/__init__.py,sha256=7Xx9MxZknT4c4QQr3F5fKDlB2hN3F2lFHqseJnlvY88,57
+opencode_llama_cpp_launcher/models/launch_config.py,sha256=r0yzTKkeRfGWVHcDXMopxGtOlr_U0FZ9wzjXFPixqaM,809
+opencode_llama_cpp_launcher/models/launch_status.py,sha256=iLcX_ZVWY4olIo4MFOKadBqipOcHyHt-WMmJdx0RPvc,398
+opencode_llama_cpp_launcher/services/__init__.py,sha256=f_O4iWCTQ1ndiuaiV4uVsEu4GGx9em0gZEWo9rB9_K8,25
+opencode_llama_cpp_launcher/services/binaries.py,sha256=Du14Wp0wGUep86HvS8x6_aqwxYCrRx6XRSCGrVJtsvM,313
+opencode_llama_cpp_launcher/services/errors.py,sha256=Zrey_carJ8Rk6eo7nJbNnm7FxJW6vDORe5nN02XomKE,121
+opencode_llama_cpp_launcher/services/health.py,sha256=gQSF9p8SzIKoEGev9P0VcsM8ampPz67fATKQVziD9Ng,2200
+opencode_llama_cpp_launcher/services/launch_config_loader.py,sha256=PJzFO_SW2EbXW7UcYvupvwB5laxz9sVg-x-3qXGPWVU,3591
+opencode_llama_cpp_launcher/services/launch_preparer.py,sha256=HZCfZalSEZYYBg2dM8hesTjcKfAGye7f6s1ERufMx7k,4361
+opencode_llama_cpp_launcher/services/launcher.py,sha256=XpvRfYrxJ3346J_2gyqRXkextJTxuT_y7SUaLNHZKfM,6783
+opencode_llama_cpp_launcher/services/opencode_config.py,sha256=OzT9V5PzGb9jxnzTBgsv_zzJnI2QzUUaaCkOrjcGtLk,897
+opencode_llama_cpp_launcher/services/ports.py,sha256=1OgE3IqZF9mpmyvBoiuV61O3aSxDlkWcs4nfE5ehIOg,528
+opencode_llama_cpp_launcher/storage/__init__.py,sha256=qNn6blTqWXGEfHe2fb5H2Jl7qCLsE7aymNYohcyc_Q4,42
+opencode_llama_cpp_launcher/storage/config_loader.py,sha256=e-RhLMI8TcWOgOEEtmbfhcId8LZtUWcNRSwsyJM17Pc,4039
+opencode_llama_cpp_launcher-0.1.0.dist-info/METADATA,sha256=eNgIVVdJdckY8Oyzyz0eXUf-OPuiDFhu5isR9afL5oI,3067
+opencode_llama_cpp_launcher-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+opencode_llama_cpp_launcher-0.1.0.dist-info/entry_points.txt,sha256=lvH_XU3XuLgcZZOCBzu6yUMIho_zkAHgGW7e-PcCyo0,83
+opencode_llama_cpp_launcher-0.1.0.dist-info/licenses/LICENSE,sha256=sFB7n5aEp0gwYBaZP1GsXm06-wvT2LHAVVXShPOTqW8,1063
+opencode_llama_cpp_launcher-0.1.0.dist-info/RECORD,,

opencode_llama_cpp_launcher-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opencode_llama_cpp_launcher-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opencode-llama = opencode_llama_cpp_launcher.cli.entrypoint:main

opencode_llama_cpp_launcher-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ribomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.