Metadata-Version: 2.4
Name: mainboard
Version: 0.0.2
Summary: CPU, GPU, and NPU hardware topology and telemetry for Python.
Author-email: Pedro Valois <contact@phvv.me>
License-Expression: Apache-2.0
Project-URL: Documentation, https://phvv.me/mainboard
Project-URL: Homepage, https://github.com/phvv-me/mainboard
Project-URL: Repository, https://github.com/phvv-me/mainboard
Project-URL: Issues, https://github.com/phvv-me/mainboard/issues
Keywords: apple-silicon,cpu,cuda,gpu,hardware,machine,npu,telemetry,topology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cyclopts<5,>=4.16
Requires-Dist: plumbum<2,>=1.10
Requires-Dist: psutil<8,>=7
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: rich>=13
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: pyrefly>=1; extra == "dev"
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: pytest-randomly>=3; extra == "dev"
Requires-Dist: ruff>=0.15; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-llmstxt>=0.2; extra == "docs"
Requires-Dist: mkdocs-static-i18n>=1.2; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Provides-Extra: nvidia
Requires-Dist: cuda-bindings<14,>=13.3; platform_system == "Linux" and extra == "nvidia"
Requires-Dist: cuda-core<2,>=1; platform_system == "Linux" and extra == "nvidia"
Requires-Dist: cuda-python<14,>=13.3; platform_system == "Linux" and extra == "nvidia"
Dynamic: license-file

<div align="center">

[![mainboard banner](https://raw.githubusercontent.com/phvv-me/mainboard/main/docs/assets/banner.png)](https://phvv.me/mainboard)

[![CI](https://github.com/phvv-me/mainboard/actions/workflows/ci.yml/badge.svg)](https://github.com/phvv-me/mainboard/actions/workflows/ci.yml)
[![Publish](https://github.com/phvv-me/mainboard/actions/workflows/publish.yml/badge.svg)](https://github.com/phvv-me/mainboard/actions/workflows/publish.yml)
[![PyPI](https://img.shields.io/pypi/v/mainboard)](https://pypi.org/project/mainboard/)
[![Python](https://img.shields.io/pypi/pyversions/mainboard)](https://pypi.org/project/mainboard/)
[![Docs](https://img.shields.io/badge/docs-phvv.me%2Fmainboard-15803d)](https://phvv.me/mainboard)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/phvv-me/mainboard/actions/workflows/ci.yml)

</div>

> **Warning** mainboard is early (`0.0.x`). The Python API is small on purpose, but provider details may still change.

## Installation

```sh
pip install mainboard
```

Working in a [chefe](https://phvv.me/chefe) project? Add it to your manifest:

```sh
chefe add mainboard -l python
```

On Linux with NVIDIA GPUs, pull the CUDA provider extra: `pip install "mainboard[nvidia]"`.

## What it is

mainboard tells Python what compute is on the current machine, without assuming the world is only CUDA. It models CPUs, GPUs, and NPUs as `Unit`s, keeps vendor-specific probing behind providers (Apple and NVIDIA today), and gives you the whole board in one call.

```python
from mainboard import Machine

print(Machine().model_dump_json(indent=2))   # cpu, memory, gpus, npus, and the host environment
```

## Usage

```python
machine = Machine()
machine.cpu.snapshot()             # CPU identity and capacity
machine.gpus[0].snapshot()         # per-GPU telemetry
machine.environment                # user, group(s), and job scheduler on the host
machine.model_dump_json()          # one-call JSON probe of the whole machine
```

The CLI renders a Rich schematic of the board:

```sh
mainboard
```
