coala-runtime 0.1.0__py3-none-any.whl

coala_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""Coala Runtime - MCP server for executing Python and R scripts in containers."""
+
+__version__ = "0.1.0"

coala_runtime/__main__.py

@@ -0,0 +1,56 @@
+"""Entry point for running the MCP server."""
+
+import sys
+
+from coala_runtime.server import mcp
+from coala_runtime.runtime.docker_images import ensure_images
+
+_HELP = """\
+usage: coala-runtime [--build]
+
+Run the Coala Runtime MCP server over stdio (tools: coala_python_executor, coala_r_executor).
+
+  --build    Build executor Docker images from the repo (requires clone + docker/)
+
+Configure an MCP client (e.g. Cursor ~/.cursor/mcp.json), replace cwd with your repo path:
+
+  "mcpServers": {
+    "coala-runtime": {
+      "command": "coala-runtime",
+      "args": [],
+      "cwd": "/path/to/coala-runtime"
+    }
+  }
+
+With uv (no global install):
+
+  "command": "uv",
+  "args": ["run", "--directory", "/path/to/coala-runtime", "coala-runtime"]
+
+More options: MCP_CONFIG.md in the coala-runtime repository.
+"""
+
+# Shown on every start (stderr only; stdout is reserved for MCP JSON-RPC).
+_MCP_START_HINT = """\
+Coala Runtime MCP (stdio). Client config: use "command": "coala-runtime", "args": [], "cwd": "<repo>".
+Alternatives: python -m coala_runtime, or uv run --directory <repo> coala-runtime. Details: MCP_CONFIG.md.
+"""
+
+
+def main() -> None:
+    """Run the MCP server (used by the coala-runtime console script)."""
+    if "-h" in sys.argv or "--help" in sys.argv:
+        print(_HELP, end="", file=sys.stdout)
+        raise SystemExit(0)
+
+    build = "--build" in sys.argv
+    if build:
+        sys.argv = [a for a in sys.argv if a != "--build"]
+
+    print(_MCP_START_HINT, file=sys.stderr, flush=True)
+    ensure_images(build=build)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

coala_runtime/runtime/__init__.py

@@ -0,0 +1 @@
+"""Runtime components for containerized script execution."""

coala_runtime/runtime/container_manager.py

@@ -0,0 +1,207 @@
+"""Container manager for Docker operations."""
+
+import asyncio
+import logging
+from typing import Dict, Optional, Sequence, Union
+
+import docker
+from docker.errors import DockerException, ImageNotFound
+
+logger = logging.getLogger(__name__)
+
+
+class ContainerManager:
+    """Manages Docker container lifecycle and operations."""
+
+    def __init__(self, docker_client: Optional[docker.DockerClient] = None):
+        """Initialize container manager.
+
+        Args:
+            docker_client: Optional Docker client. If None, creates a new client.
+        """
+        self.client = docker_client or docker.from_env()
+        self.containers: Dict[str, docker.models.containers.Container] = {}
+
+    async def ensure_image(self, image: str) -> None:
+        """Pull ``image`` from a registry if it is not already present locally.
+
+        ``docker.containers.create`` fails with 404 when the image only exists on a
+        remote registry (e.g. quay.io/biocontainers/...). This matches ``docker run``
+        behavior, which pulls missing images by default.
+        """
+        loop = asyncio.get_event_loop()
+
+        def _ensure() -> None:
+            try:
+                self.client.images.get(image)
+                logger.debug("Docker image present locally: %s", image)
+            except ImageNotFound:
+                logger.info("Docker image not found locally, pulling: %s", image)
+                self.client.images.pull(image)
+                logger.info("Pulled Docker image: %s", image)
+
+        await loop.run_in_executor(None, _ensure)
+
+    async def create_container(
+        self,
+        image: str,
+        command: Optional[str] = None,
+        volumes: Optional[Dict[str, Dict[str, str]]] = None,
+        working_dir: str = "/workspace",
+        environment: Optional[Dict[str, str]] = None,
+        name: Optional[str] = None,
+    ) -> docker.models.containers.Container:
+        """Create a Docker container.
+
+        Args:
+            image: Docker image name
+            command: Command to run in container
+            volumes: Volume bind mounts (host_path: {bind: container_path, mode: mode})
+            working_dir: Working directory in container
+            environment: Environment variables
+            name: Optional container name
+
+        Returns:
+            Created container object
+        """
+        try:
+            await self.ensure_image(image)
+            # Run in executor to avoid blocking
+            loop = asyncio.get_event_loop()
+            container = await loop.run_in_executor(
+                None,
+                lambda: self.client.containers.create(
+                    image=image,
+                    command=command if command else None,
+                    volumes=volumes or {},
+                    working_dir=working_dir,
+                    environment=environment or {},
+                    name=name,
+                    detach=True,
+                    stdin_open=True,
+                    tty=True,
+                ),
+            )
+            container_id = container.id
+            self.containers[container_id] = container
+            logger.info(
+                f"Created container {container_id[:12]} from image {image} with command: {command}"
+            )
+            return container
+        except DockerException as e:
+            logger.error(f"Failed to create container: {e}")
+            raise
+
+    async def start_container(self, container: docker.models.containers.Container) -> None:
+        """Start a container.
+
+        Args:
+            container: Container to start
+        """
+        try:
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, container.start)
+            # Refresh container to get updated status
+            container.reload()
+            logger.info(f"Started container {container.id[:12]} (status: {container.status})")
+        except DockerException as e:
+            logger.error(f"Failed to start container: {e}")
+            raise
+
+    async def exec_command(
+        self,
+        container: docker.models.containers.Container,
+        command: Union[str, Sequence[str]],
+        workdir: Optional[str] = None,
+        environment: Optional[Dict[str, str]] = None,
+    ) -> tuple[int, bytes, bytes]:
+        """Execute a command in a running container.
+
+        Args:
+            container: Container to execute command in
+            command: Shell string or argv list (list avoids shell quoting issues)
+            workdir: Working directory for command
+            environment: Environment variables
+
+        Returns:
+            Tuple of (exit_code, stdout, stderr)
+        """
+        try:
+            # Refresh container status to ensure it's running
+            container.reload()
+            if container.status != "running":
+                raise DockerException(
+                    f"Container {container.id[:12]} is not running (status: {container.status})"
+                )
+
+            loop = asyncio.get_event_loop()
+            exec_result = await loop.run_in_executor(
+                None,
+                lambda: container.exec_run(
+                    command,
+                    workdir=workdir,
+                    environment=environment or {},
+                    stdout=True,
+                    stderr=True,
+                ),
+            )
+            exit_code = exec_result.exit_code
+            output = exec_result.output
+            # Split stdout and stderr (Docker API returns combined output)
+            # For simplicity, we'll return the combined output as stdout
+            # and empty stderr (actual stderr is in container logs)
+            return exit_code, output, b""
+        except DockerException as e:
+            logger.error(f"Failed to execute command in container: {e}")
+            raise
+
+    async def get_logs(
+        self, container: docker.models.containers.Container, tail: int = 1000
+    ) -> str:
+        """Get container logs.
+
+        Args:
+            container: Container to get logs from
+            tail: Number of lines to retrieve
+
+        Returns:
+            Container logs as string
+        """
+        try:
+            loop = asyncio.get_event_loop()
+            logs_bytes = await loop.run_in_executor(
+                None, lambda: container.logs(tail=tail, stdout=True, stderr=True)
+            )
+            return logs_bytes.decode("utf-8", errors="replace")
+        except DockerException as e:
+            logger.error(f"Failed to get container logs: {e}")
+            return f"Error retrieving logs: {e}"
+
+    async def remove_container(
+        self, container: docker.models.containers.Container, force: bool = True
+    ) -> None:
+        """Remove a container.
+
+        Args:
+            container: Container to remove
+            force: Force removal even if running
+        """
+        try:
+            container_id = container.id
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, lambda: container.remove(force=force))
+            if container_id in self.containers:
+                del self.containers[container_id]
+            logger.info(f"Removed container {container_id[:12]}")
+        except DockerException as e:
+            logger.warning(f"Failed to remove container: {e}")
+
+    async def cleanup_all(self) -> None:
+        """Remove all managed containers."""
+        for container in list(self.containers.values()):
+            await self.remove_container(container)
+
+    def __del__(self):
+        """Cleanup on deletion."""
+        # Note: This is a fallback, but async cleanup should be done explicitly
+        pass

coala_runtime/runtime/docker_images.py

@@ -0,0 +1,123 @@
+"""Ensure required Docker images exist; pull from registry or build locally."""
+
+import logging
+import subprocess
+from pathlib import Path
+
+import docker
+from docker.errors import DockerException, ImageNotFound
+
+logger = logging.getLogger(__name__)
+
+# Default images used by executors; pulled if missing
+PULL_IMAGES = [
+    "hubentu/coala-runtime-python:latest",
+    "hubentu/coala-runtime-r:latest",
+]
+
+
+def _project_root() -> Path | None:
+    """Return project root (directory containing docker/ and Dockerfiles), or None."""
+    # Prefer cwd so "uv run --directory /path/to/coala-runtime" or running from
+    # project dir works when the package is installed (e.g. conda).
+    cwd = Path.cwd()
+    if cwd.joinpath("docker", "Dockerfile.python").exists():
+        return cwd
+    # Walk up from this file (works when running from source tree).
+    path = Path(__file__).resolve().parent
+    for _ in range(5):
+        if path.joinpath("docker", "Dockerfile.python").exists():
+            return path
+        parent = path.parent
+        if parent == path:
+            break
+        path = parent
+    return None
+
+
+def _image_exists(client, image_tag: str) -> bool:
+    """Return True if the image exists locally."""
+    try:
+        client.images.get(image_tag)
+        return True
+    except ImageNotFound:
+        return False
+
+
+def _pull_image(client, image: str) -> None:
+    """Pull image from registry."""
+    logger.info("Pulling %s...", image)
+    client.images.pull(image)
+    logger.info("Pulled %s", image)
+
+
+def _build_image(client, project_root: Path, dockerfile_rel: str, tag: str) -> None:
+    """Build a single image. dockerfile_rel is relative to project_root."""
+    logger.info("Building Docker image %s from %s...", tag, dockerfile_rel)
+    build_path = str(project_root)
+    try:
+        image, gen = client.images.build(
+            path=build_path,
+            dockerfile=dockerfile_rel,
+            tag=tag,
+        )
+        for chunk in gen:
+            if "stream" in chunk:
+                logger.debug(chunk["stream"].rstrip())
+    except ImageNotFound:
+        # docker-py may raise after build when resolving image by ID; image can
+        # still be present by tag (e.g. with buildx or some Docker versions).
+        try:
+            client.images.get(tag)
+        except ImageNotFound:
+            raise
+    logger.info("Built image %s", tag)
+
+
+def _run_build_script(project_root: Path) -> None:
+    """Run docker/build.sh to build both images locally."""
+    script = project_root / "docker" / "build.sh"
+    if not script.exists():
+        raise FileNotFoundError(f"Build script not found: {script}")
+    logger.info("Running %s...", script)
+    subprocess.run(
+        ["bash", str(script)],
+        cwd=str(project_root),
+        check=True,
+    )
+
+
+def ensure_images(*, build: bool = False) -> None:
+    """Ensure required executor images exist.
+
+    By default, pulls hubentu/coala-runtime-python:latest and hubentu/coala-runtime-r:latest
+    from Docker Hub if not present. With build=True, runs docker/build.sh to build both
+    images locally (tagged as coala-runtime-python:latest and coala-runtime-r:latest).
+    """
+    try:
+        client = docker.from_env()
+    except DockerException as e:
+        logger.warning(
+            "Could not connect to Docker; skipping image check/build: %s", e
+        )
+        return
+
+    if build:
+        project_root = _project_root()
+        if project_root is None or not project_root.joinpath("docker", "Dockerfile.python").exists():
+            logger.warning(
+                "Could not find project root (run from coala-runtime repo or set cwd); skipping Docker image build"
+            )
+            return
+        _run_build_script(project_root)
+        return
+
+    for image in PULL_IMAGES:
+        if _image_exists(client, image):
+            logger.debug("Docker image %s already present", image)
+            continue
+        try:
+            _pull_image(client, image)
+        except DockerException as e:
+            logger.error("Failed to pull %s: %s", image, e)
+            raise