atlas-runner 0.1.0__tar.gz

atlas_runner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ATTMOS Inc. 
+
+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.

atlas_runner-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: atlas-runner
+Version: 0.1.0
+Summary: A runtime abstraction layer for ATLAS — container orchestration via Docker with a pluggable backend interface.
+Author: ATTMOS Inc.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ATTMOS/atlas-runner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: typer<1,>=0.9
+Requires-Dist: rich<14,>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file

atlas_runner-0.1.0/README.md

@@ -0,0 +1,115 @@
+# atlas-runner
+
+A runtime abstraction layer for ATLAS. Provides a library and CLI that launches and manages workloads using Docker (v0), with a backend interface designed to support Apptainer/Singularity in future releases. Used by atlas-agent for deterministic container execution, lifecycle control, status, logs, and resource enforcement.
+
+## Requirements
+
+- Python >= 3.11
+- Docker Engine (accessible via `docker` CLI)
+
+## Installation
+
+```bash
+pip install atlas-runner
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+### Library usage
+
+```python
+from atlas_runner import Runner, RunSpec, create_backend
+
+# Create a runner with the Docker backend
+runner = Runner(create_backend("docker"))
+
+# Pull an image and run a container
+runner.pull("alpine:latest")
+result = runner.run(RunSpec(
+    name="my-task",
+    image="alpine:latest",
+    command=["echo", "hello"],
+))
+print(result.container_id, result.started_at)
+
+# Check status and fetch logs
+status = runner.status("my-task")
+print(status.state, status.exit_code)
+logs = runner.logs("my-task")
+
+# Clean up
+runner.destroy("my-task")
+```
+
+### CLI usage
+
+```bash
+# Authenticate with a registry
+atlas-runner login registry.io -u user --password-stdin < token.txt
+
+# Pull an image
+atlas-runner pull alpine:latest
+
+# Run a container with resource limits
+atlas-runner run --name my-task --image alpine:latest \
+    --cmd echo --cmd hello \
+    --cpu-cores 4 --memory-gb 16
+
+# Run with GPU access
+atlas-runner run --name gpu-task --image nvidia/cuda:12.0-base \
+    --gpu 0 --gpu 1 \
+    --shell "python train.py"
+
+# Check status (human-readable or JSON)
+atlas-runner status my-task
+atlas-runner --json status my-task
+
+# View logs
+atlas-runner logs my-task
+
+# List all containers
+atlas-runner ps
+atlas-runner --json ps
+
+# Stop and remove
+atlas-runner destroy my-task
+```
+
+## Configuration
+
+| Option | CLI Flag | Description |
+|---|---|---|
+| Backend | `--backend docker` | Container runtime backend (default: `docker`) |
+| Docker host | `--docker-host tcp://remote:2375` | Docker daemon socket URL |
+| JSON output | `--json` | Output structured JSON instead of human-readable text |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Lint and format
+ruff check src/ tests/
+ruff format --check src/ tests/
+
+# Type check
+mypy src/
+```
+
+## API Reference
+
+See [docs/api.md](docs/api.md) for the full API reference.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

atlas_runner-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atlas-runner"
+description = "A runtime abstraction layer for ATLAS — container orchestration via Docker with a pluggable backend interface."
+version = "0.1.0"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "ATTMOS Inc." }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "pydantic>=2.5,<3",
+    "typer>=0.9,<1",
+    "rich>=13.0,<14",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.3",
+    "mypy>=1.8",
+]
+
+[project.urls]
+Repository = "https://github.com/ATTMOS/atlas-runner"
+
+[project.scripts]
+atlas-runner = "atlas_runner.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["atlas_runner"]
+mypy_path = "src"

atlas_runner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

atlas_runner-0.1.0/src/atlas_runner/__init__.py

@@ -0,0 +1,27 @@
+"""Atlas Runner — container orchestration via Docker."""
+
+from atlas_runner._version import __version__
+from atlas_runner.errors import ErrorCode, RunnerError
+from atlas_runner.models import (
+    ContainerState,
+    ContainerStatus,
+    Mount,
+    RunResult,
+    RunSpec,
+)
+from atlas_runner.protocol import RunnerBackend
+from atlas_runner.runner import Runner, create_backend
+
+__all__ = [
+    "__version__",
+    "ContainerState",
+    "ContainerStatus",
+    "create_backend",
+    "ErrorCode",
+    "Mount",
+    "Runner",
+    "RunnerBackend",
+    "RunnerError",
+    "RunResult",
+    "RunSpec",
+]

atlas_runner-0.1.0/src/atlas_runner/_docker_cli.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from typing import Any
+
+from atlas_runner.errors import ErrorCode, RunnerError
+
+_DAEMON_MARKERS = (
+    "cannot connect to the docker daemon",
+    "is the docker daemon running",
+    "connection refused",
+)
+
+
+class DockerCLI:
+    """Low-level wrapper around the ``docker`` CLI.
+
+    Every Docker operation in atlas-runner goes through this class so that
+    ``subprocess.run`` is isolated to a single module (clean mock boundary).
+    """
+
+    def __init__(self, docker_host: str | None = None) -> None:
+        self._base: list[str] = ["docker"]
+        if docker_host is not None:
+            self._base = ["docker", "--host", docker_host]
+
+    # ------------------------------------------------------------------
+    # Core executor
+    # ------------------------------------------------------------------
+
+    def _run(
+        self,
+        args: list[str],
+        *,
+        check: bool = True,
+        capture_output: bool = True,
+        input_data: str | None = None,
+        timeout: int | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        cmd = self._base + args
+        try:
+            result = subprocess.run(
+                cmd,
+                check=False,
+                capture_output=capture_output,
+                text=True,
+                input=input_data,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RunnerError(
+                code=ErrorCode.BACKEND_ERROR,
+                message=f"Docker command timed out after {timeout}s",
+                details={"command": cmd, "timeout": timeout},
+            ) from exc
+
+        if check and result.returncode != 0:
+            stderr = result.stderr.strip() if result.stderr else ""
+            if any(m in stderr.lower() for m in _DAEMON_MARKERS):
+                raise RunnerError(
+                    code=ErrorCode.DOCKER_DAEMON_UNAVAILABLE,
+                    message="Docker daemon is not available",
+                    details={"stderr": stderr},
+                )
+            raise RunnerError(
+                code=ErrorCode.BACKEND_ERROR,
+                message=f"Docker command failed (exit {result.returncode})",
+                details={"command": cmd, "stderr": stderr},
+            )
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Public methods
+    # ------------------------------------------------------------------
+
+    def login(
+        self,
+        registry: str,
+        username: str,
+        password: str,
+    ) -> None:
+        try:
+            self._run(
+                ["login", "--username", username, "--password-stdin", registry],
+                input_data=password,
+            )
+        except RunnerError as exc:
+            if exc.code == ErrorCode.BACKEND_ERROR:
+                raise RunnerError(
+                    code=ErrorCode.LOGIN_FAILED,
+                    message=f"Login failed for registry: {registry}",
+                    details=exc.details,
+                ) from exc
+            raise
+
+    def pull(self, image: str) -> None:
+        try:
+            self._run(["pull", image])
+        except RunnerError as exc:
+            if exc.code == ErrorCode.BACKEND_ERROR:
+                raise RunnerError(
+                    code=ErrorCode.IMAGE_PULL_FAILED,
+                    message=f"Failed to pull image: {image}",
+                    details=exc.details,
+                ) from exc
+            raise
+
+    def run(self, args: list[str]) -> str:
+        result = self._run(["run"] + args)
+        return result.stdout.strip()
+
+    def stop(self, name: str) -> None:
+        self._run(["stop", name], check=False)
+
+    def rm(self, name: str) -> None:
+        self._run(["rm", name], check=False)
+
+    def inspect(self, name: str) -> dict[str, Any]:
+        result = self._run(["inspect", name])
+        data: list[dict[str, Any]] = json.loads(result.stdout)
+        return data[0]
+
+    def ps(self, filters: list[str] | None = None) -> list[dict[str, Any]]:
+        args = ["ps", "--format", "{{json .}}", "--no-trunc"]
+        for f in filters or []:
+            args.extend(["--filter", f])
+        result = self._run(args)
+        entries: list[dict[str, Any]] = []
+        for line in result.stdout.strip().splitlines():
+            if line:
+                entries.append(json.loads(line))
+        return entries
+
+    def logs(self, name: str) -> str:
+        result = self._run(["logs", name])
+        return result.stdout
+
+    def container_exists(self, name: str) -> bool:
+        escaped = re.escape(name)
+        result = self._run(
+            ["ps", "-a", "--filter", f"name=^/{escaped}$", "--format", "{{.ID}}"],
+        )
+        return bool(result.stdout.strip())

atlas_runner-0.1.0/src/atlas_runner/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"