gpustack-runtime 0.2.5.post2__tar.gz → 0.2.5.post4__tar.gz

gpustack_runtime-0.2.5.post4/ADOPTERS.md

@@ -0,0 +1,12 @@
+# Who's using GPUStack Runtime
+
+GPUStack Runtime is used by a growing range of companies and projects to detect accelerator (GPU/NPU) resources and run accelerator workloads on Docker, Kubernetes and Podman.
+
+If you are using GPUStack Runtime and your name is not on this list, please send us a PR!
+
+## Companies/Projects using GPUStack Runtime in production
+
+These companies and projects are using GPUStack Runtime in production. If your company is using GPUStack Runtime, open a PR to add your company or project name and a description of how you are using GPUStack Runtime.
+
+| Company / Project | Use Case |
+| --- | --- |

gpustack_runtime-0.2.5.post4/AGENTS.md

@@ -0,0 +1,85 @@
+# GPUStack Runtime
+
+A Python library with a unified interface for detecting accelerator (GPU/NPU) resources and
+launching and managing GPU workloads on Docker, Kubernetes and Podman.
+
+## Project Structure
+
+- `gpustack_runtime/` — the library.
+  - `detector/` — one detector per vendor (`nvidia.py`, `amd.py`, `ascend.py`, `cambricon.py`,
+    `hygon.py`, `iluvatar.py`, `metax.py`, `mthreads.py`, `thead.py`), plus the `py*` packages,
+    ctypes bindings to vendor management libraries (`pynvml`, `pydcmi`, `pycndev`, ...).
+  - `deployer/` — one deployer per container runtime (`docker.py`, `kubernetes.py`, `podman.py`),
+    `cdi/` for vendor CDI spec handling, `k8s/` for Kubernetes helpers, and `__patches__.py` for
+    the vendored Podman client patch.
+  - `cmds/` — CLI subcommands behind the `gpustack-runtime` entrypoint (`__main__.py`).
+  - `envs.py` — environment variables; `logging.py` — logging helpers.
+- `tests/gpustack_runtime/` — pytest suite mirroring the package; `detector/samples/` holds
+  captured vendor-tool outputs used as fixtures.
+- `docs/` — MkDocs site; `docs/modules/` is API reference rendered from docstrings by
+  mkdocstrings.
+- `specs/` — design records.
+- `pack/` / `deploy/` — container image build and deployment manifests.
+
+## Architecture
+
+Detection: each vendor detector in `gpustack_runtime/detector/` probes its vendor library through
+the matching `py*` binding and reports `Device`s with topology. `detector/__init__.py` owns the
+registry (`_DETECTORS`) and the aggregate entry points (`supported_list()`, `detect_devices()`).
+
+Deployment: `deployer/__init__.py` owns the registry (`_DEPLOYERS`) and picks the first available
+runtime (Docker, Kubernetes, Podman). A `WorkloadPlan` describes the desired containers; the
+deployer injects vendor resources (CDI devices, environment variables, mounts) and returns a
+workload handle for inspect/logs/exec/delete. Shared types live in `deployer/__types__.py`,
+including the `OperationError` / `UnsupportedError` error contract.
+
+## Finding sources
+
+- Confirm the checkout, branch and uncommitted changes before reasoning about behavior. The
+  published wheel or a merged PR may describe a different revision.
+- Docstrings are the usage contract: `make docs` renders them into `site/`. Specs under
+  `specs/` own design rationale; current code establishes what this checkout implements. Report
+  disagreement rather than silently choosing one.
+- For a vendor behavior claim, read the matching `py*` binding and the detector tests under
+  `tests/gpustack_runtime/detector/`; captured outputs live in `detector/samples/`.
+- For a concrete error, search its stable text locally first. When it concerns an upstream
+  dependency (docker, kubernetes, podman clients), check that project's issues and pinned version
+  in `pyproject.toml` / `uv.lock`.
+
+## Development
+
+Setup is `make install` (uv sync plus pre-commit hooks). Day-to-day targets:
+
+- `make lint` — pre-commit on all files: ruff check/format, codespell, commitizen.
+- `make test` — pytest.
+- `make docs` — build the MkDocs site into `site/` (git-ignored).
+- `make build` — build wheel and sdist into `dist/` (git-ignored).
+- `make package` — build the container image with docker buildx; `PACKAGE_PUSH=true` pushes.
+
+`gpustack_runtime/_version.py` is generated by hatch-vcs and `_version_appendix.py` by
+`make prepare`; never hand-edit either.
+
+### Python conventions
+
+- Prefer clarity over cleverness to simplify long-term maintenance.
+- Start every package module with `from __future__ import annotations as __future_annotations__`.
+- Follow the ruff configuration in `ruff.toml`; run `make lint` whenever modifying Python source.
+- Type-annotate public APIs and re-export them from the package `__init__.py` (`__all__`).
+- Write Google-style docstrings; they render into the published API reference.
+- Handle errors explicitly. Deployers raise `OperationError` or `UnsupportedError` from
+  `deployer.__types__` instead of leaking runtime-client exceptions. Detectors degrade to an
+  empty result and log at debug level rather than failing on a host without that vendor.
+- Keep private helpers in double-underscore modules (`__types__.py`, `__utils__.py`); import them
+  through the package, not across subpackages.
+- Keep concurrency simple, safe and justified; minimize mutable shared state.
+- Keep comments plain and short: no emoji, no decorative symbols. State the point in words.
+
+### Testing conventions
+
+- pytest; tests mirror the package layout under `tests/gpustack_runtime/`.
+- Never require real hardware or a real container runtime. Detector tests fake the `py*` vendor
+  binding in the test module; deployer tests fake the runtime client.
+- Reuse captured vendor outputs from `tests/gpustack_runtime/detector/samples/` and shared
+  fixtures from `fixtures/` instead of inventing new sample data.
+- Verify one behavior or contract per test; assert observable state, not implementation details.
+- Keep tests deterministic and repeatable: no wall-clock, ordering or randomness dependence.

gpustack_runtime-0.2.5.post4/DCO

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

{gpustack_runtime-0.2.5.post2 → gpustack_runtime-0.2.5.post4}/LICENSE

@@ -175,7 +175,7 @@ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
 END OF TERMS AND CONDITIONS
 
-Copyright (c) 2025 The GPUStack Authors
+Copyright (c) 2026 The GPUStack Authors
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

gpustack_runtime-0.2.5.post4/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: gpustack-runtime
+Version: 0.2.5.post4
+Summary: GPUStack Runtime is library for detecting GPU resources and launching GPU workloads.
+Project-URL: Homepage, https://github.com/gpustack/runtime
+Project-URL: Bug Tracker, https://github.com/gpustack/gpustack/issues
+Author-email: GPUStack Authors <contact@gpustack.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: argcomplete>=3.6.3
+Requires-Dist: cachetools>=5.5.2
+Requires-Dist: docker>=7.1.0
+Requires-Dist: gpustack-runner>=0.1.29
+Requires-Dist: kubernetes>=33.1.0
+Requires-Dist: mthreads-ml-py>=2.2.10
+Requires-Dist: nvidia-ml-py>=13.580.65
+Requires-Dist: podman==5.6.0
+Requires-Dist: pyyaml
+Requires-Dist: tqdm
+Description-Content-Type: text/markdown
+
+# GPUStack Runtime
+
+[![License](https://img.shields.io/github/license/gpustack/runtime?logo=apache&label=License)](./LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/gpustack-runtime?logo=pypi&label=PyPI)](https://pypi.org/project/gpustack-runtime/)
+[![Latest Release](https://img.shields.io/github/v/release/gpustack/runtime?logo=semanticrelease&label=Release&include_prereleases)](https://github.com/gpustack/runtime/releases/latest)
+[![Docker Pulls](https://img.shields.io/docker/pulls/gpustack/runtime?logo=docker&logoColor=fff&label=Docker%20Pulls)](https://hub.docker.com/r/gpustack/runtime)
+[![Ask DeepWiki](https://img.shields.io/badge/Ask_DeepWiki-purple?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAPoAAAD6AG1e1JrAAACIUlEQVRYw+2XP2gUQRTGv7d3JhYWQawkIBaCVWzETos0gmAnVoKNTSoLK0E7EQQrC20sBVFBtLPQRgTBtBaKjYgIQUSxiJq7fT+LvCGPJZdNLt4dQj5Y3u7sznzfzLw/s9IO/icANiniCujEfWdsQgBLxAbsbraPZcmBfcAt4DNwKQsZNfEUsAB8YRV12LfA6ZHuedg7AO7ed/c+UBcbQhbiu+6wXIM6EnZWkszMJe2Ke0n6I2la0v51hFeSMLN6OwIK6jJwEBdUYb2MAxRSz6sY4geiahFgLe1Hwq6YWe3us8AN4FQQU4QM64SPY69Xyr43fADgNjAPXHb3peSsD4FDQ0VLEjAHvIhBPS6AHvA1bBO9JPAXcHFbIRtJ5yzwIQZ9CZwAusDJENIkLqsG8DpNyIZJwSUk9wLHgakcesC1JCCjiHm1kYDNOEjptCxpSVK/8f73OFLxPLAYM3oCzEX7MXf/lJbc/8kWpA4HgQdpYI9IWAbeh83whi84cHXL+58EPBoQhnmm94EzwE3gZ2p/Dhzdbhg+TaRr01x7ftb4/jBwFzjXrCvDpmLW9crVLNeR9CaapoGemb2TdCERW1tNaBNQ8jktwmozqwtpqRNtdWAjARYk39IS12ZWRX7vmJmA71nQZgi36gN7gCvAj5xc3P0jcH7kx7Ik5IC73wsh14GZsZySow5002l4Jr0b6+m4eSyvpAn8lEzsx2QHo8RfUrlN+uPq4ksAAAAASUVORK5CYII=)](https://deepwiki.com/gpustack/runtime)
+
+GPUStack Runtime offers a unified interface for detecting GPU resources and managing GPU workloads.
+
+## Features
+
+- Detect a wide range of GPU and accelerator resources:
+
+  - AMD GPU
+  - Ascend NPU
+  - Cambricon MLU
+  - Hygon DCU
+  - Iluvatar GPU
+  - MetaX GPU
+  - Moore Threads GPU
+  - NVIDIA GPU
+  - T-Head PPU
+
+- Manage GPU workloads on the following platforms:
+
+  - Docker
+  - Kubernetes
+  - Podman (>=4.9, experimental support via the `CONTAINER_HOST=http+unix:///path/to/podman/socket` environment variable)
+
+Contributions to support additional GPU resources are welcome!
+
+## Installation
+
+```bash
+pip install gpustack-runtime
+```
+
+## Documentation
+
+The API reference renders from docstrings. Build the site locally with `make docs` and open
+`site/index.html`.
+
+## Contributing
+
+Contributions are welcome. Commits must carry a `Signed-off-by` line certifying the
+[Developer Certificate of Origin](./DCO).
+
+Using GPUStack Runtime in production? Add your company or project to [ADOPTERS.md](./ADOPTERS.md)
+via pull request.
+
+## License
+
+Copyright (c) 2026 The GPUStack Authors. Licensed under the
+[Apache License 2.0](./LICENSE).

gpustack_runtime-0.2.5.post4/README.md

@@ -0,0 +1,55 @@
+# GPUStack Runtime
+
+[![License](https://img.shields.io/github/license/gpustack/runtime?logo=apache&label=License)](./LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/gpustack-runtime?logo=pypi&label=PyPI)](https://pypi.org/project/gpustack-runtime/)
+[![Latest Release](https://img.shields.io/github/v/release/gpustack/runtime?logo=semanticrelease&label=Release&include_prereleases)](https://github.com/gpustack/runtime/releases/latest)
+[![Docker Pulls](https://img.shields.io/docker/pulls/gpustack/runtime?logo=docker&logoColor=fff&label=Docker%20Pulls)](https://hub.docker.com/r/gpustack/runtime)
+[![Ask DeepWiki](https://img.shields.io/badge/Ask_DeepWiki-purple?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAPoAAAD6AG1e1JrAAACIUlEQVRYw+2XP2gUQRTGv7d3JhYWQawkIBaCVWzETos0gmAnVoKNTSoLK0E7EQQrC20sBVFBtLPQRgTBtBaKjYgIQUSxiJq7fT+LvCGPJZdNLt4dQj5Y3u7sznzfzLw/s9IO/icANiniCujEfWdsQgBLxAbsbraPZcmBfcAt4DNwKQsZNfEUsAB8YRV12LfA6ZHuedg7AO7ed/c+UBcbQhbiu+6wXIM6EnZWkszMJe2Ke0n6I2la0v51hFeSMLN6OwIK6jJwEBdUYb2MAxRSz6sY4geiahFgLe1Hwq6YWe3us8AN4FQQU4QM64SPY69Xyr43fADgNjAPXHb3peSsD4FDQ0VLEjAHvIhBPS6AHvA1bBO9JPAXcHFbIRtJ5yzwIQZ9CZwAusDJENIkLqsG8DpNyIZJwSUk9wLHgakcesC1JCCjiHm1kYDNOEjptCxpSVK/8f73OFLxPLAYM3oCzEX7MXf/lJbc/8kWpA4HgQdpYI9IWAbeh83whi84cHXL+58EPBoQhnmm94EzwE3gZ2p/Dhzdbhg+TaRr01x7ftb4/jBwFzjXrCvDpmLW9crVLNeR9CaapoGemb2TdCERW1tNaBNQ8jktwmozqwtpqRNtdWAjARYk39IS12ZWRX7vmJmA71nQZgi36gN7gCvAj5xc3P0jcH7kx7Ik5IC73wsh14GZsZySow5002l4Jr0b6+m4eSyvpAn8lEzsx2QHo8RfUrlN+uPq4ksAAAAASUVORK5CYII=)](https://deepwiki.com/gpustack/runtime)
+
+GPUStack Runtime offers a unified interface for detecting GPU resources and managing GPU workloads.
+
+## Features
+
+- Detect a wide range of GPU and accelerator resources:
+
+  - AMD GPU
+  - Ascend NPU
+  - Cambricon MLU
+  - Hygon DCU
+  - Iluvatar GPU
+  - MetaX GPU
+  - Moore Threads GPU
+  - NVIDIA GPU
+  - T-Head PPU
+
+- Manage GPU workloads on the following platforms:
+
+  - Docker
+  - Kubernetes
+  - Podman (>=4.9, experimental support via the `CONTAINER_HOST=http+unix:///path/to/podman/socket` environment variable)
+
+Contributions to support additional GPU resources are welcome!
+
+## Installation
+
+```bash
+pip install gpustack-runtime
+```
+
+## Documentation
+
+The API reference renders from docstrings. Build the site locally with `make docs` and open
+`site/index.html`.
+
+## Contributing
+
+Contributions are welcome. Commits must carry a `Signed-off-by` line certifying the
+[Developer Certificate of Origin](./DCO).
+
+Using GPUStack Runtime in production? Add your company or project to [ADOPTERS.md](./ADOPTERS.md)
+via pull request.
+
+## License
+
+Copyright (c) 2026 The GPUStack Authors. Licensed under the
+[Apache License 2.0](./LICENSE).

{gpustack_runtime-0.2.5.post2 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/_version.py

@@ -27,8 +27,8 @@ version_tuple: VERSION_TUPLE
 __commit_id__: COMMIT_ID
 commit_id: COMMIT_ID
 
-__version__ = version = '0.2.5.post2'
-__version_tuple__ = version_tuple = (0, 2, 5, 'post2')
+__version__ = version = '0.2.5.post4'
+__version_tuple__ = version_tuple = (0, 2, 5, 'post4')
 try:
     from ._version_appendix import git_commit
     __commit_id__ = commit_id = git_commit

gpustack_runtime-0.2.5.post4/gpustack_runtime/_version_appendix.py

@@ -0,0 +1 @@
+git_commit = "089358e"

{gpustack_runtime-0.2.5.post2 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/deployer/__init__.py

@@ -36,7 +36,8 @@ from .docker import (
     DockerWorkloadPlan,
     DockerWorkloadStatus,
 )
-from .kuberentes import (
+from .k8s.devicemanager import KubernetesResourceInjectionPolicyEnum
+from .kubernetes import (
     KubernetesDeployer,
     KubernetesWorkloadPlan,
     KubernetesWorkloadStatus,
@@ -245,7 +246,7 @@ def logs_workload(
         tail:
             The number of lines from the end of the logs to show.
         since:
-            Show logs since a given time (in seconds).
+            Show logs since the given epoch in seconds.
         follow:
             Whether to follow the logs.
 
@@ -300,7 +301,7 @@ async def async_logs_workload(
         tail:
             The number of lines from the end of the logs to show.
         since:
-            Show logs since a given time (in seconds).
+            Show logs since the given epoch in seconds.
         follow:
             Whether to follow the logs.
 
@@ -434,7 +435,7 @@ def logs_self(
         tail:
             The number of lines from the end of the logs to show.
         since:
-            Show logs since a given time (in seconds).
+            Show logs since the given epoch in seconds.
         follow:
             Whether to follow the logs.
 
@@ -479,7 +480,7 @@ async def async_logs_self(
         tail:
             The number of lines from the end of the logs to show.
         since:
-            Show logs since a given time (in seconds).
+            Show logs since the given epoch in seconds.
         follow:
             Whether to follow the logs.
 
@@ -595,6 +596,7 @@ __all__ = [
     "ContainerSecurity",
     "DockerWorkloadPlan",
     "DockerWorkloadStatus",
+    "KubernetesResourceInjectionPolicyEnum",
     "KubernetesWorkloadPlan",
     "KubernetesWorkloadStatus",
     "OperationError",

{gpustack_runtime-0.2.5.post2 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/deployer/docker.py

@@ -2105,7 +2105,7 @@ class DockerDeployer(EndoscopicDeployer):
 
         logs_options = {
             "timestamps": timestamps,
-            "tail": tail if tail >= 0 else None,
+            "tail": tail if tail is not None and tail >= 0 else None,
             "since": since,
             "follow": follow,
         }

{gpustack_runtime-0.2.5.post2 → gpustack_runtime-0.2.5.post4}/gpustack_runtime/deployer/k8s/devicemanager/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations as __future_annotations__
 
 import stat
+from enum import Enum
 from functools import lru_cache
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
@@ -11,6 +12,36 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
 
+class KubernetesResourceInjectionPolicyEnum(str, Enum):
+    """
+    Device injection policies for Kubernetes workloads.
+    """
+
+    AUTO = "Auto"
+    """
+    Detect the policy from the target node's allocatable resources.
+    """
+    ENV = "Env"
+    """
+    Inject runtime-visible device environment variables without device-plugin requests.
+    """
+    KDP = "KDP"
+    """
+    Request device-plugin resources.
+    """
+
+    @classmethod
+    def _missing_(cls, value: object) -> KubernetesResourceInjectionPolicyEnum | None:
+        if isinstance(value, str):
+            for member in cls:
+                if member.value.lower() == value.lower():
+                    return member
+        return None
+
+    def __str__(self) -> str:
+        return self.value
+
+
 def is_kubelet_socket_accessible(
     kubelet_endpoint: Path | None = None,
 ) -> bool:
@@ -79,13 +110,16 @@ def node_has_device_plugin_resources(
 
 def get_resource_injection_policy(
     probe_node_allocatable: Callable[[], Mapping[str, Any] | None] | None = None,
+    *,
+    policy: KubernetesResourceInjectionPolicyEnum | None = None,
 ) -> Literal["env", "kdp"]:
     """
     Get the resource injection policy (in lowercase) for the deployer.
 
-    An explicit policy always wins. Under "auto" the decision belongs to the
-    cluster, not to the process doing the deploying: the Kubernetes deployer
-    orchestrates remotely, so whether *it* can reach a kubelet socket says
+    A workload policy overrides the environment setting. Under "auto" the
+    decision belongs to the cluster, not to the process doing the deploying:
+    the Kubernetes deployer orchestrates remotely, so whether *it* can reach
+    a kubelet socket says
     nothing about whether the *target* node runs a device plugin. So the probe
     reads that node's allocatable resources and looks for a device-plugin
     resource family there.
@@ -99,14 +133,29 @@ def get_resource_injection_policy(
         probe_node_allocatable:
             Called only under the "auto" policy, to read the target node's
             allocatable resources. Returns None when the node cannot be read.
+        policy:
+            Workload policy override. None inherits the environment setting;
+            Auto probes the node even if the environment selects Env or KDP.
+
+    Raises:
+        ValueError:
+            If the policy is not Auto, Env or KDP.
 
     Returns:
         The resource injection policy.
 
     """
-    policy = envs.GPUSTACK_RUNTIME_KUBERNETES_RESOURCE_INJECTION_POLICY.lower()
-    if policy != "auto":
-        return policy
+    if policy is None:
+        policy = envs.GPUSTACK_RUNTIME_KUBERNETES_RESOURCE_INJECTION_POLICY
+    try:
+        policy = KubernetesResourceInjectionPolicyEnum(policy)
+    except ValueError as e:
+        msg = f"Invalid resource injection policy '{policy}'"
+        raise ValueError(msg) from e
+    if policy == KubernetesResourceInjectionPolicyEnum.ENV:
+        return "env"
+    if policy == KubernetesResourceInjectionPolicyEnum.KDP:
+        return "kdp"
 
     if probe_node_allocatable is None:
         return "kdp"
@@ -142,6 +191,7 @@ def cdi_kind_to_kdp_resource(
 
 
 __all__ = [
+    "KubernetesResourceInjectionPolicyEnum",
     "cdi_kind_to_kdp_resource",
     "get_resource_injection_policy",
     "is_kubelet_socket_accessible",