omnismi 1.0.0__tar.gz

omnismi-1.0.0/LICENSE

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

omnismi-1.0.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.2
+Name: omnismi
+Version: 1.0.0
+Summary: Cross-vendor GPU observability for AI agents and Python apps (NVIDIA and AMD today)
+Author: Omnismi Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/omnismi/omnismi
+Project-URL: Repository, https://github.com/omnismi/omnismi
+Project-URL: Documentation, https://github.com/omnismi/omnismi/tree/main/docs
+Keywords: gpu,cross-vendor,nvidia,amd,observability,ai-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: all
+Requires-Dist: nvidia-ml-py>=11.525.84; extra == "all"
+Requires-Dist: amdsmi>=6.0.0; extra == "all"
+Provides-Extra: nvidia
+Requires-Dist: nvidia-ml-py>=11.525.84; extra == "nvidia"
+Provides-Extra: amd
+Requires-Dist: amdsmi>=6.0.0; extra == "amd"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: isort>=5.13; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+
+# Omnismi
+
+Cross-vendor GPU observability for AI agents and Python apps (NVIDIA and AMD today).
+
+Omnismi provides a compact and stable Python API for reading GPU information and metrics across vendors.
+The long-term goal is broader vendor coverage without changing user-facing API contracts.
+
+## Why Omnismi
+
+- Unified API across vendors: `count`, `gpus`, `gpu`, `info`, `metrics`.
+- Fixed normalized units: bytes, percent, Celsius, Watts, MHz.
+- Graceful degradation: unavailable metrics return `None` instead of raising by default.
+- NVIDIA psutil-style cached sampling plus `GPU.realtime()` for forced live reads.
+- Built-in parity checker to compare normalized output with direct vendor readings.
+
+## Why not just torch/pynvml/amdsmi?
+
+PyTorch memory APIs are useful in framework workflows, but are framework-scoped and not designed as a
+cross-vendor observability contract for general runtime checks. Direct vendor bindings are essential,
+but each has different lifecycle, naming, and compatibility details. Omnismi adds a stable cross-vendor
+contract for agent preflight and application telemetry. See [docs/why-omnismi.md](docs/why-omnismi.md).
+
+## Adapter Matrix (Ground Truth Libraries)
+
+| Vendor | Runtime/Driver Stack | Ground Truth Library | Router Status |
+|---|---|---|---|
+| NVIDIA | CUDA + NVML | `nvidia-ml-py` | ✅ Supported |
+| AMD | ROCm + AMD SMI | `amdsmi` | ✅ Supported |
+| Intel | oneAPI + Level Zero | TBD | ⬜ Planned |
+| Apple | Metal | TBD | ⬜ Planned |
+
+Status legend:
+- `✅ Supported`: Adapter path is integrated and maintained.
+- `🟡 Partial`: Adapter is integrated but some metrics/features are incomplete.
+- `🧪 Awaiting User Validation`: Adapter path exists; model/version evidence is still needed.
+- `⬜ Planned`: Vendor adapter is not integrated yet.
+
+## Hardware Validation Status
+
+| Vendor | Model | Status | Evidence |
+|---|---|---|---|
+| NVIDIA | H20 | ✅ Verified | [v1.0.0 release note](CHANGELOG.md#100---2026-02-25) |
+| AMD | MI300X | ✅ Verified | [v1.0.0 release note](CHANGELOG.md#100---2026-02-25) |
+
+See full matrix in [docs/compatibility.md](docs/compatibility.md).
+
+## Install
+
+Omnismi core is lightweight and has no mandatory vendor dependency.
+Pick the install command that matches your environment:
+
+| Your environment | What to install | Command |
+|---|---|---|
+| No GPU / CI / just developing API integration | Core package only | `pip install omnismi` |
+| NVIDIA GPUs only | Core + NVIDIA backend dependency | `pip install "omnismi[nvidia]"` |
+| AMD GPUs only | Core + AMD backend dependency | `pip install "omnismi[amd]"` |
+| Mixed cluster or shared image | Core + NVIDIA + AMD dependencies | `pip install "omnismi[all]"` |
+
+### Install From Local Source
+
+```bash
+# from repo root
+python -m pip install -e ".[all]"
+```
+
+If you only need one vendor backend during local development:
+
+```bash
+python -m pip install -e ".[nvidia]"
+# or
+python -m pip install -e ".[amd]"
+```
+
+## Quick Start
+
+```python
+import omnismi as omi
+
+# 1) Count GPUs
+gpu_count = omi.count()
+
+# 2) Check whether GPU exists
+has_gpu = gpu_count > 0
+
+# 3) Get max total GPU memory (bytes) across visible devices
+max_memory_bytes = max(
+    (dev.info().memory_total_bytes or 0 for dev in omi.gpus()),
+    default=0,
+)
+
+print(f"gpu_count={gpu_count}")
+print(f"has_gpu={has_gpu}")
+print(f"max_memory_bytes={max_memory_bytes}")
+```
+
+## API
+
+- `omi.count() -> int`
+- `omi.gpus() -> list[GPU]`
+- `omi.gpu(index: int) -> GPU | None`
+- `GPU.info() -> GPUInfo`
+- `GPU.metrics() -> GPUMetrics`
+- `GPU.realtime() -> context manager` (force live reads when backend supports it)
+
+## Current Support and Semantics
+
+| Vendor | Status | Backend dependency | Read semantics |
+|---|---|---|---|
+| NVIDIA | Supported | `nvidia-ml-py` | Read-only, normalized units, unavailable values return `None` |
+| AMD | Supported | `amdsmi` | Read-only, normalized units, unavailable values return `None` |
+| Other vendors (Intel, Apple, etc.) | Planned | TBD | Same API contract (`count/gpus/gpu`, `info/metrics`) |
+
+| Metric field | Unit | Semantic |
+|---|---|---|
+| `utilization_percent` | `%` | GPU utilization percentage when available |
+| `memory_used_bytes` / `memory_total_bytes` | `bytes` | Memory usage/total in bytes |
+| `temperature_c` | `C` | Device temperature in Celsius |
+| `power_w` | `W` | Power usage in Watts |
+| `core_clock_mhz` / `memory_clock_mhz` | `MHz` | Core/memory clock when available |
+
+### Sampling Semantics (NVIDIA)
+
+- Omnismi initializes NVML lazily on first NVIDIA backend use (`nvmlInit`).
+- `GPU.metrics()` is psutil-style for NVIDIA: repeated calls return the latest cached sample instead of reading NVML every call.
+- A background sampler refreshes cached metrics periodically (default 0.5s interval).
+- On process exit or backend teardown, Omnismi calls `nvmlShutdown()`.
+
+Use realtime mode only when you explicitly need per-call direct reads:
+
+```python
+import omnismi as omi
+
+dev = omi.gpu(0)
+if dev is not None:
+    with dev.realtime():
+        live = dev.metrics()  # bypass cache for this call path
+```
+
+## Roadmap (Todo)
+
+- Extend backend coverage to more GPU vendors.
+- Improve compatibility matrix depth across drivers/runtimes/architectures.
+- Strengthen parity validation workflow and reporting.
+- Expand hardware-backed tests and reproducibility tooling.
+- Keep API minimal while improving metric quality and consistency.
+
+## Documentation
+
+- API and usage docs: `docs/`
+- Build docs locally: `mkdocs serve`
+- Parity validation: `python -m omnismi.validation.parity --vendor nvidia --samples 3`
+
+## Local Validation
+
+```bash
+# run unit tests
+PYTHONPATH=src pytest -q
+
+# compare normalized output against direct vendor API
+PYTHONPATH=src python -m omnismi.validation.parity --vendor nvidia --samples 3
+PYTHONPATH=src python -m omnismi.validation.parity --vendor amd --samples 3
+```
+
+## License
+
+MIT

omnismi-1.0.0/README.md

@@ -0,0 +1,166 @@
+# Omnismi
+
+Cross-vendor GPU observability for AI agents and Python apps (NVIDIA and AMD today).
+
+Omnismi provides a compact and stable Python API for reading GPU information and metrics across vendors.
+The long-term goal is broader vendor coverage without changing user-facing API contracts.
+
+## Why Omnismi
+
+- Unified API across vendors: `count`, `gpus`, `gpu`, `info`, `metrics`.
+- Fixed normalized units: bytes, percent, Celsius, Watts, MHz.
+- Graceful degradation: unavailable metrics return `None` instead of raising by default.
+- NVIDIA psutil-style cached sampling plus `GPU.realtime()` for forced live reads.
+- Built-in parity checker to compare normalized output with direct vendor readings.
+
+## Why not just torch/pynvml/amdsmi?
+
+PyTorch memory APIs are useful in framework workflows, but are framework-scoped and not designed as a
+cross-vendor observability contract for general runtime checks. Direct vendor bindings are essential,
+but each has different lifecycle, naming, and compatibility details. Omnismi adds a stable cross-vendor
+contract for agent preflight and application telemetry. See [docs/why-omnismi.md](docs/why-omnismi.md).
+
+## Adapter Matrix (Ground Truth Libraries)
+
+| Vendor | Runtime/Driver Stack | Ground Truth Library | Router Status |
+|---|---|---|---|
+| NVIDIA | CUDA + NVML | `nvidia-ml-py` | ✅ Supported |
+| AMD | ROCm + AMD SMI | `amdsmi` | ✅ Supported |
+| Intel | oneAPI + Level Zero | TBD | ⬜ Planned |
+| Apple | Metal | TBD | ⬜ Planned |
+
+Status legend:
+- `✅ Supported`: Adapter path is integrated and maintained.
+- `🟡 Partial`: Adapter is integrated but some metrics/features are incomplete.
+- `🧪 Awaiting User Validation`: Adapter path exists; model/version evidence is still needed.
+- `⬜ Planned`: Vendor adapter is not integrated yet.
+
+## Hardware Validation Status
+
+| Vendor | Model | Status | Evidence |
+|---|---|---|---|
+| NVIDIA | H20 | ✅ Verified | [v1.0.0 release note](CHANGELOG.md#100---2026-02-25) |
+| AMD | MI300X | ✅ Verified | [v1.0.0 release note](CHANGELOG.md#100---2026-02-25) |
+
+See full matrix in [docs/compatibility.md](docs/compatibility.md).
+
+## Install
+
+Omnismi core is lightweight and has no mandatory vendor dependency.
+Pick the install command that matches your environment:
+
+| Your environment | What to install | Command |
+|---|---|---|
+| No GPU / CI / just developing API integration | Core package only | `pip install omnismi` |
+| NVIDIA GPUs only | Core + NVIDIA backend dependency | `pip install "omnismi[nvidia]"` |
+| AMD GPUs only | Core + AMD backend dependency | `pip install "omnismi[amd]"` |
+| Mixed cluster or shared image | Core + NVIDIA + AMD dependencies | `pip install "omnismi[all]"` |
+
+### Install From Local Source
+
+```bash
+# from repo root
+python -m pip install -e ".[all]"
+```
+
+If you only need one vendor backend during local development:
+
+```bash
+python -m pip install -e ".[nvidia]"
+# or
+python -m pip install -e ".[amd]"
+```
+
+## Quick Start
+
+```python
+import omnismi as omi
+
+# 1) Count GPUs
+gpu_count = omi.count()
+
+# 2) Check whether GPU exists
+has_gpu = gpu_count > 0
+
+# 3) Get max total GPU memory (bytes) across visible devices
+max_memory_bytes = max(
+    (dev.info().memory_total_bytes or 0 for dev in omi.gpus()),
+    default=0,
+)
+
+print(f"gpu_count={gpu_count}")
+print(f"has_gpu={has_gpu}")
+print(f"max_memory_bytes={max_memory_bytes}")
+```
+
+## API
+
+- `omi.count() -> int`
+- `omi.gpus() -> list[GPU]`
+- `omi.gpu(index: int) -> GPU | None`
+- `GPU.info() -> GPUInfo`
+- `GPU.metrics() -> GPUMetrics`
+- `GPU.realtime() -> context manager` (force live reads when backend supports it)
+
+## Current Support and Semantics
+
+| Vendor | Status | Backend dependency | Read semantics |
+|---|---|---|---|
+| NVIDIA | Supported | `nvidia-ml-py` | Read-only, normalized units, unavailable values return `None` |
+| AMD | Supported | `amdsmi` | Read-only, normalized units, unavailable values return `None` |
+| Other vendors (Intel, Apple, etc.) | Planned | TBD | Same API contract (`count/gpus/gpu`, `info/metrics`) |
+
+| Metric field | Unit | Semantic |
+|---|---|---|
+| `utilization_percent` | `%` | GPU utilization percentage when available |
+| `memory_used_bytes` / `memory_total_bytes` | `bytes` | Memory usage/total in bytes |
+| `temperature_c` | `C` | Device temperature in Celsius |
+| `power_w` | `W` | Power usage in Watts |
+| `core_clock_mhz` / `memory_clock_mhz` | `MHz` | Core/memory clock when available |
+
+### Sampling Semantics (NVIDIA)
+
+- Omnismi initializes NVML lazily on first NVIDIA backend use (`nvmlInit`).
+- `GPU.metrics()` is psutil-style for NVIDIA: repeated calls return the latest cached sample instead of reading NVML every call.
+- A background sampler refreshes cached metrics periodically (default 0.5s interval).
+- On process exit or backend teardown, Omnismi calls `nvmlShutdown()`.
+
+Use realtime mode only when you explicitly need per-call direct reads:
+
+```python
+import omnismi as omi
+
+dev = omi.gpu(0)
+if dev is not None:
+    with dev.realtime():
+        live = dev.metrics()  # bypass cache for this call path
+```
+
+## Roadmap (Todo)
+
+- Extend backend coverage to more GPU vendors.
+- Improve compatibility matrix depth across drivers/runtimes/architectures.
+- Strengthen parity validation workflow and reporting.
+- Expand hardware-backed tests and reproducibility tooling.
+- Keep API minimal while improving metric quality and consistency.
+
+## Documentation
+
+- API and usage docs: `docs/`
+- Build docs locally: `mkdocs serve`
+- Parity validation: `python -m omnismi.validation.parity --vendor nvidia --samples 3`
+
+## Local Validation
+
+```bash
+# run unit tests
+PYTHONPATH=src pytest -q
+
+# compare normalized output against direct vendor API
+PYTHONPATH=src python -m omnismi.validation.parity --vendor nvidia --samples 3
+PYTHONPATH=src python -m omnismi.validation.parity --vendor amd --samples 3
+```
+
+## License
+
+MIT

omnismi-1.0.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=64.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "omnismi"
+version = "1.0.0"
+description = "Cross-vendor GPU observability for AI agents and Python apps (NVIDIA and AMD today)"
+keywords = ["gpu", "cross-vendor", "nvidia", "amd", "observability", "ai-agent"]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Omnismi Contributors"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.optional-dependencies]
+all = [
+    "nvidia-ml-py>=11.525.84",
+    "amdsmi>=6.0.0",
+]
+nvidia = [
+    "nvidia-ml-py>=11.525.84",
+]
+amd = [
+    "amdsmi>=6.0.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.8",
+    "black>=24.0",
+    "isort>=5.13",
+    "ruff>=0.6",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/omnismi/omnismi"
+Repository = "https://github.com/omnismi/omnismi"
+Documentation = "https://github.com/omnismi/omnismi/tree/main/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.isort]
+profile = "black"
+line-length = 88
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.9"
+strict = false
+warn_return_any = true
+warn_unused_configs = true

omnismi-1.0.0/setup.cfg

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

omnismi-1.0.0/src/omnismi/__init__.py

@@ -0,0 +1,19 @@
+"""Omnismi: unified, minimal GPU observability API."""
+
+from omnismi.api import GPU, count, gpu, gpus
+from omnismi.errors import BackendError, OmnismiError, ValidationError
+from omnismi.models import GPUMetrics, GPUInfo
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BackendError",
+    "GPU",
+    "GPUInfo",
+    "GPUMetrics",
+    "OmnismiError",
+    "ValidationError",
+    "count",
+    "gpu",
+    "gpus",
+]

omnismi-1.0.0/src/omnismi/api.py

@@ -0,0 +1,112 @@
+"""Public Omnismi API."""
+
+from __future__ import annotations
+
+from contextlib import nullcontext
+import time
+from dataclasses import replace
+from typing import Any
+
+from omnismi.backends.base import BaseBackend
+from omnismi.backends.registry import active_backends
+from omnismi.models import GPUMetrics, GPUInfo
+
+
+class GPU:
+    """Lightweight GPU object with psutil-style read methods."""
+
+    __slots__ = ("_backend", "_device", "_index")
+
+    def __init__(self, backend: BaseBackend, device: Any, index: int) -> None:
+        self._backend = backend
+        self._device = device
+        self._index = index
+
+    @property
+    def index(self) -> int:
+        """Global Omnismi GPU index."""
+        return self._index
+
+    def info(self) -> GPUInfo:
+        """Return static information for this GPU."""
+        try:
+            info = self._backend.info(self._device, self._index)
+            if info.index != self._index:
+                info = replace(info, index=self._index)
+            return info
+        except Exception:
+            return GPUInfo(
+                index=self._index,
+                vendor=self._backend.vendor,
+                name=f"{self._backend.vendor.upper()} GPU {self._index}",
+                uuid=None,
+                driver=None,
+                memory_total_bytes=None,
+            )
+
+    def metrics(self) -> GPUMetrics:
+        """Return current metrics for this GPU."""
+        try:
+            metrics = self._backend.metrics(self._device, self._index)
+            if metrics.index != self._index:
+                metrics = replace(metrics, index=self._index)
+            return metrics
+        except Exception:
+            return GPUMetrics(
+                index=self._index,
+                utilization_percent=None,
+                memory_used_bytes=None,
+                memory_total_bytes=None,
+                temperature_c=None,
+                power_w=None,
+                core_clock_mhz=None,
+                memory_clock_mhz=None,
+                timestamp_ns=time.time_ns(),
+            )
+
+    def realtime(self):
+        """Return a context that forces live metric reads when supported by backend."""
+        mode = getattr(self._backend, "realtime_mode", None)
+        if callable(mode):
+            try:
+                return mode()
+            except Exception:
+                return nullcontext()
+        return nullcontext()
+
+    def __repr__(self) -> str:
+        return f"GPU(index={self._index}, vendor={self._backend.vendor!r})"
+
+
+def gpus() -> list[GPU]:
+    """Return all currently visible GPUs across all active backends."""
+    devices: list[GPU] = []
+    next_index = 0
+
+    for backend in active_backends():
+        try:
+            backend_devices = backend.devices()
+        except Exception:
+            continue
+
+        for device in backend_devices:
+            devices.append(GPU(backend=backend, device=device, index=next_index))
+            next_index += 1
+
+    return devices
+
+
+def count() -> int:
+    """Return the number of currently visible GPUs."""
+    return len(gpus())
+
+
+def gpu(index: int) -> GPU | None:
+    """Return a single GPU by global index, or None if out of range."""
+    if index < 0:
+        return None
+
+    for device in gpus():
+        if device.index == index:
+            return device
+    return None

omnismi-1.0.0/src/omnismi/backends/__init__.py

@@ -0,0 +1,15 @@
+"""Backend implementations for supported GPU vendors."""
+
+from omnismi.backends.amd import AmdBackend
+from omnismi.backends.base import BaseBackend
+from omnismi.backends.nvidia import NvidiaBackend
+from omnismi.backends.registry import active_backends, close_all, registered_backends
+
+__all__ = [
+    "AmdBackend",
+    "BaseBackend",
+    "NvidiaBackend",
+    "active_backends",
+    "registered_backends",
+    "close_all",
+]