vmware-privateai 1.0.0__tar.gz

vmware_privateai-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

vmware_privateai-1.0.0/LICENSE

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

vmware_privateai-1.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: vmware-privateai
+Version: 1.0.0
+Summary: VMware Private AI Foundation with NVIDIA ops — GPU inventory, vGPU/DirectPath profiles, utilization, model-serving (MCP + CLI)
+Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-ops,gpu,mcp,nvidia,private-ai,vcf,vgpu,vmware
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: pyvmomi<10.0,>=8.0.3.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<15.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: vmware-policy<2.0,>=1.8.8
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.vmware-skills/vmware-privateai -->
+
+# VMware Private AI (Foundation with NVIDIA) — GPU & Model-Serving Ops
+
+> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with,
+> endorsed by, or sponsored by VMware, Inc., Broadcom Inc., or NVIDIA Corporation.** "VMware", "vSphere",
+> and "VCF" are trademarks of Broadcom; "NVIDIA" is a trademark of NVIDIA. Source is auditable at
+> [github.com/vmware-skills/VMware-PrivateAI](https://github.com/vmware-skills/VMware-PrivateAI) under the MIT license.
+
+> **Status: pre-MVP skeleton (2026-08-06).** Skill #15 of the VMware family. Manages the **GPU / AI-infrastructure
+> layer** of VMware Private AI Foundation with NVIDIA (PAIF-N) on vSphere 9.x / VCF 9.1 — GPU host/device
+> inventory, vGPU & DirectPath profiles, GPU consumers and utilization, vGPU assignment, and Private AI
+> Service (PAIS) model serving. Independent 1.x version line.
+
+Companion of **vmware-aiops** (the vCenter VMs behind AI workloads), **vmware-vks** (GPU-enabled Kubernetes),
+and **vmware-monitor** (read-only health). This skill is the GPU lens over all three.
+
+Every API path is verified against official Broadcom/NVIDIA docs before use (see
+`tests/eval/spec/privateai_endpoints.py`) — no endpoints written from memory.

vmware_privateai-1.0.0/README-CN.md

@@ -0,0 +1,82 @@
+<!-- mcp-name: io.github.vmware-skills/vmware-privateai -->
+
+# VMware Private AI(Foundation with NVIDIA)—— GPU 与模型服务运维
+
+VMware skill 家族的 **GPU / AI 基础设施** 视角 —— GPU 主机与设备清点、vGPU 消费者、实时 GPU 利用率、
+vGPU / DirectPath 配置目录、vGPU 分配,以及 **Private AI Service(PAIS)** 的已服务模型与知识库,
+覆盖 **vSphere 9.x / VCF 9.1** Web Services API(pyVmomi)与 PAIS REST API。MCP server + CLI。
+
+> **声明**:社区维护的开源项目,**与 VMware, Inc.、Broadcom Inc.、NVIDIA Corporation 无任何隶属、背书或
+> 赞助关系。** "VMware"、"vSphere"、"VCF" 为 Broadcom 商标;"NVIDIA"、"vGPU" 为 NVIDIA 商标。源码遵循
+> MIT 许可,公开可审计:[github.com/vmware-skills/VMware-PrivateAI](https://github.com/vmware-skills/VMware-PrivateAI)。
+
+> **状态:v1.0.0(beta)。** 家族第 15 个 skill,走独立 1.x 版本线。每条 API 路径在使用前都对照官方
+> Broadcom/NVIDIA 资料核实(见 `tests/eval/spec/privateai_endpoints.py`)——不凭记忆编写端点。GET 响应
+> **字段名** 与 PAIS 的确切路径为防御式,待真机 9.x 硬件验证(见下方 beta 活口)。由家族 harness 治理
+> (审计 + 策略 + 教学性错误);读写授权交由 vCenter 服务账号的 RBAC 角色。
+
+## 能力(10 工具:9 读 / 1 写)
+
+| 类别 | 工具 | 读/写 |
+|------|------|:----:|
+| **GPU 清点** | 主机 列表/详情、设备列表、vGPU 消费者列表 | 4 读 |
+| **GPU 利用率** | 每台 vGPU 虚机实时利用率(GPU %、显存 %、温度) | 1 读 |
+| **配置目录** | vGPU 配置列表、DirectPath 配置列表 | 2 读 |
+| **vGPU 分配** | 设置虚机 vGPU 配置(虚机须已关机) | 1 写 |
+| **Private AI Service** | 已服务模型列表、知识库列表 | 2 读 |
+
+读操作严格无破坏性。唯一的写(`vgpu_assign`)会预览爆炸半径、拒绝已开机虚机、**绝不自行关机**、
+CLI 双重确认、统一审计到 `~/.vmware/audit.db`。
+
+## 快速开始
+
+```bash
+uv tool install vmware-privateai
+vmware-privateai version
+vmware-privateai gpu host-list        # 第一条读命令 —— 列出有 GPU 的主机
+```
+
+配置位于 `~/.vmware-privateai/config.yaml`(targets + 可选 `pais:` 段);密码与 PAIS bearer token 存于
+`~/.vmware-privateai/.env`(chmod 600)。详见 `skills/vmware-privateai/references/setup-guide.md`。
+
+## 典型工作流
+
+**1. 找空闲 GPU 并给虚机换 vGPU 配置**
+```bash
+vmware-privateai gpu device-list --vendor NVIDIA   # vm_count 0 = 空闲
+vmware-privateai gpu consumer-list                 # 谁持有 vGPU、什么配置
+vmware-privateai vgpu profile-list --host esx-07   # 该主机可分配的配置
+vmware-privateai gpu vgpu-assign fin-train-01 grid_a100-4c --dry-run   # 预览
+# 先用 vmware-aiops 关机,再:
+vmware-privateai gpu vgpu-assign fin-train-01 grid_a100-4c            # 双重确认 + 审计
+```
+*失败分支*:提示 "VM is powered on" 时,先 `vmware-aiops vm_power_off 'fin-train-01'`;提示配置不被主机
+提供 / 显存不足时,`vmware-privateai gpu host-get <该主机>` 查看有效配置。
+
+**2. 全域 GPU 利用率巡检**
+```bash
+vmware-privateai gpu utilization --top 10
+```
+*失败分支*:显示 `metrics unavailable` 不是错误 —— NVIDIA 主机 GPU 驱动未暴露该虚机的计数器。更深的
+per-SM / MIG-slice 遥测 vSphere 不提供(需 NVIDIA DCGM)。
+
+**3. 查看 PAIS 正在服务什么**
+```bash
+vmware-privateai pais model-list
+vmware-privateai pais kb-list
+```
+*失败分支*:HTTP 404 通常是 base-URL 不匹配(`/api/v1` 前缀随部署而异、beta 未确认),查 `pais.endpoint`;
+HTTP 401/403 表示 `VMWARE_PRIVATEAI_PAIS_TOKEN` 过期或缺权限,重新取 token。
+
+## Companion Skills
+- [vmware-aiops](https://github.com/vmware-skills/VMware-AIops) —— AI 负载背后的 vCenter 虚机(开关机/快照/克隆/迁移)
+- [vmware-vks](https://github.com/vmware-skills/VMware-VKS) —— GPU 使能的 Tanzu Kubernetes
+- [vmware-monitor](https://github.com/vmware-skills/VMware-Monitor) —— 只读 vSphere 健康
+
+## 安全
+详见仓库根目录 `SECURITY.md`。要点:凭据仅存 `.env`(chmod 600、`b64:` 混淆);默认开启 TLS 校验;
+所有 vSphere/PAIS 文本经 `vmware_policy.sanitize()` 防注入;读写授权交由 vCenter RBAC;
+`vgpu_assign` 关机门控 + 双重确认 + 审计。
+
+## License
+MIT

vmware_privateai-1.0.0/README.md

@@ -0,0 +1,19 @@
+<!-- mcp-name: io.github.vmware-skills/vmware-privateai -->
+
+# VMware Private AI (Foundation with NVIDIA) — GPU & Model-Serving Ops
+
+> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with,
+> endorsed by, or sponsored by VMware, Inc., Broadcom Inc., or NVIDIA Corporation.** "VMware", "vSphere",
+> and "VCF" are trademarks of Broadcom; "NVIDIA" is a trademark of NVIDIA. Source is auditable at
+> [github.com/vmware-skills/VMware-PrivateAI](https://github.com/vmware-skills/VMware-PrivateAI) under the MIT license.
+
+> **Status: pre-MVP skeleton (2026-08-06).** Skill #15 of the VMware family. Manages the **GPU / AI-infrastructure
+> layer** of VMware Private AI Foundation with NVIDIA (PAIF-N) on vSphere 9.x / VCF 9.1 — GPU host/device
+> inventory, vGPU & DirectPath profiles, GPU consumers and utilization, vGPU assignment, and Private AI
+> Service (PAIS) model serving. Independent 1.x version line.
+
+Companion of **vmware-aiops** (the vCenter VMs behind AI workloads), **vmware-vks** (GPU-enabled Kubernetes),
+and **vmware-monitor** (read-only health). This skill is the GPU lens over all three.
+
+Every API path is verified against official Broadcom/NVIDIA docs before use (see
+`tests/eval/spec/privateai_endpoints.py`) — no endpoints written from memory.

vmware_privateai-1.0.0/RELEASE_NOTES.md

@@ -0,0 +1,74 @@
+# Release Notes — vmware-privateai
+
+## v1.0.0 (beta) — 2026-08-06
+
+First release. Skill #15 of the VMware skill family; the **GPU / AI-infrastructure lens** for VMware
+Private AI Foundation with NVIDIA (PAIF-N) on vSphere 9.x / VCF 9.1. Independent 1.x version line (a new
+skill starts at its own 1.0.0, not the family 1.8.x).
+
+### MCP tools — 10 (9 read, 1 write)
+
+GPU inventory (read):
+- `gpu_host_list` — ESXi hosts that have at least one GPU (filter name / vendor).
+- `gpu_host_get` — full per-GPU detail for one host (device, type, memory, consumers).
+- `gpu_device_list` — flattened physical GPU devices across hosts (`vm_count 0` = idle).
+- `gpu_consumer_list` — VMs consuming a vGPU and the profile each holds.
+
+GPU utilization (read):
+- `gpu_utilization` — real-time per-vGPU-VM utilization (gpu %, mem %, mem_used_kb, temp), busiest first.
+
+Profile catalog (read):
+- `vgpu_profile_list` — the vGPU profile catalog aggregated across hosts (framebuffer, class, sharing).
+- `directpath_profile_list` — vCenter-level DirectPath (dynamic passthrough) profiles, vSphere 9.0+.
+
+Private AI Service (read):
+- `pais_model_list` — models served by PAIS (OpenAI-compatible `/models`).
+- `pais_knowledge_base_list` — PAIS knowledge bases (RAG vector stores).
+
+vGPU assignment (write):
+- `vgpu_assign` — set/replace a VM's vGPU profile via ReconfigVM. Previews by default; requires the VM
+  powered off; never powers it off itself; double-confirmed at the CLI; audited.
+
+A matching CLI ships for all ten (`gpu`, `vgpu`, `pais` command groups) plus `version` and `mcp`.
+
+### Governed-ops harness
+
+- Every tool is wrapped by `vmware-policy`'s `@vmware_tool` (MCP) / `@guarded` (CLI write) — pre-checks,
+  policy engine, audit to `~/.vmware/audit.db`, teaching-error formatting.
+- All vSphere- and PAIS-supplied text passes through `vmware_policy.sanitize()` (≤500-char truncation +
+  C0/C1 control-char stripping) before reaching the model.
+- REST error translation is centralized in the PAIS client's `_request` (踩坑 #37); vSphere connection
+  errors become teaching `ConfigError` / `ConnectionError` messages, not tracebacks.
+- Reads paginate at 50 with a `{items, returned, limit, offset, total, truncated, hint}` envelope
+  (empty items + `truncated:false` = checked-and-none, never read as "no problem").
+- **Anti-phantom-endpoint gate**: every runtime pyVmomi path, perf counter, and PAIS REST path is pinned
+  in `tests/eval/spec/privateai_endpoints.py` and asserted by a regression test — no endpoint written
+  from model memory (踩坑 #36). MCP server lives under `vmware_privateai.mcp_server` (namespaced, never a
+  top-level `mcp_server` — 踩坑 #41); tool signatures use `Optional[X]`, not PEP 604 (踩坑 #33).
+
+### Beta activation caveats (honest, pending first real-hardware run)
+
+This release is functionally complete and import-clean, with regression coverage over its error paths,
+but has **not yet been exercised against live 9.x GPU hardware**. Before relying on it in production,
+run the read tools once against a real target and confirm:
+
+- **GET-response field names are INFERRED / defensive.** vGPU-profile, GPU-device, and consumer
+  projections read every field with `getattr` / `.get()` and degrade an absent field to empty rather than
+  crashing. A field that a live build names differently will surface as a blank column, not an error —
+  file an issue with the raw `gpu host-get` / `vgpu profile-list` output so the projection can be pinned.
+- **PAIS exact paths are INFERRED_EXACT.** The `/api/v1` prefix and the JSON response shape are
+  corroborated by the rendered Broadcom developer portal, **not** by a downloaded OpenAPI JSON or a live
+  deployment. A 404 usually means a base-URL mismatch (check `pais.endpoint`), not a bug; the response
+  parser accepts both a bare array and a `{data|items|models|knowledge_bases|…}` envelope.
+- **`gpu.*` perf counters may be host-level on some builds.** The four `gpu.*` counters are verified to
+  exist, but whether they report per-VM or per-host on a given ESXi build must be confirmed on real
+  hardware — verify the entity type before reading per-VM utilization as authoritative.
+- **MIG has no vSphere API.** MIG mode set, GPU driver version, and deep per-SM / per-process / MIG-slice
+  telemetry are **not** available through vCenter (use `nvidia-smi` / NVIDIA DCGM on the host). The code
+  lists these under `NO_API` and deliberately invents no endpoint for them.
+
+### Security
+
+- Passwords and the PAIS bearer token live only in `~/.vmware-privateai/.env` (chmod 600, `b64:`
+  obfuscated at rest). Read-vs-write authorization is delegated to the vCenter RBAC role.
+- `bandit -r vmware_privateai/`: target 0 Medium+ issues. See `SECURITY.md`.

vmware_privateai-1.0.0/SECURITY.md

@@ -0,0 +1,75 @@
+# Security Policy
+
+## Disclaimer
+Community-maintained open-source project, **not affiliated with, endorsed by, or sponsored by VMware,
+Inc., Broadcom Inc., or NVIDIA Corporation.** "VMware", "vSphere", and "VCF" are trademarks of Broadcom;
+"NVIDIA" and "vGPU" are trademarks of NVIDIA Corporation.
+
+## Reporting Vulnerabilities
+Please open a GitHub private security advisory at
+https://github.com/vmware-skills/VMware-PrivateAI/security/advisories or email the maintainer. Do not
+file public issues for security reports.
+
+## Security Design
+
+### Credential Management
+- vCenter/ESXi passwords and the PAIS bearer token live only in `~/.vmware-privateai/.env` (chmod 600),
+  obfuscated to `b64:` at rest (obfuscation, not encryption; it defeats casual grep / shoulder-surfing,
+  not a determined reader). Config files hold host / username / port and the `pais.endpoint` only.
+- Per-target env vars `VMWARE_PRIVATEAI_<TARGET>_PASSWORD` (and the `VMWARE_PRIVATEAI_PAIS_TOKEN` bearer
+  token) can be injected from a secret manager (Vault / CyberArk / AWS SM / Kubernetes Secret) instead
+  of `.env` — the code reads the environment either way.
+- Username + password are resolved together on every call (both are lazily-read properties) so a
+  rotating credential sidecar never half-updates the pair.
+
+### Authorization — delegated to vCenter RBAC
+The skill ships full read + one write and does not gate read-vs-write itself. Point a target at a
+read-only vCenter service account and the single write (`vgpu_assign`'s `ReconfigVM_Task`) is refused at
+vCenter, un-bypassably — the one place the control cannot be stepped around by a shell. Recommend a
+dedicated service account scoped to the GPU clusters.
+
+### `vgpu_assign` write safety
+`vgpu_assign` is the only state-changing tool. Its safety model:
+- **Power-off gate.** A vGPU change requires the VM to be powered **off** (no hot-add, no vMotion for
+  passthrough — VERIFIED). `confirm=false` (the default) previews only — current profile, target
+  profile, power state, and `requires_power_off` — without acting. `confirm=true` applies it but refuses
+  a powered-on VM with a teaching error.
+- **Never powers the VM off itself.** Powering the VM off is `vmware-aiops`'s job, kept separate so this
+  tool's blast radius stays "one VM, when it is already off". The refusal routes the operator to
+  `vmware-aiops vm_power_off`.
+- **Edits only the existing vGPU device.** The reconfigure targets the VM's existing vGPU device
+  (selected by the same `backing.vgpu` predicate the preview uses), never a plain DirectPath / SR-IOV
+  `VirtualPCIPassthrough`, so it cannot silently convert a full-GPU passthrough into a vGPU device.
+- **Honest outcome.** It waits for the real `ReconfigVM_Task` to finish and reports/audits the actual
+  result (a bad profile or insufficient framebuffer fails asynchronously) — never a premature "ok".
+- **CLI double-confirm + `--dry-run`.** The CLI `gpu vgpu-assign` command requires two confirmations and
+  supports `--dry-run`.
+- **Audited.** Every applied change (and every error) is recorded to `~/.vmware/audit.db` via the
+  `@vmware_tool` harness, and to the CLI companion `~/.vmware-privateai/audit.log`.
+
+### PAIS response sanitization
+Private AI Service REST responses are the highest-value prompt-injection surface in this skill — a
+knowledge-base description is operator/attacker-authored free text. All PAIS-supplied strings (model ids,
+`owned_by`, KB id/name/status/description), and all vSphere-supplied strings (device / vendor / VM /
+vGPU-profile names), pass through `vmware_policy.sanitize()` (≤500-char truncation + C0/C1 control-char
+stripping) at projection time before they reach the model.
+
+### SSL/TLS Verification
+On by default. `verify_ssl: false` (per vCenter/ESXi target) and `pais.verify_ssl: false` are intended
+only for self-signed lab certificates. The PAIS client centralizes all HTTP / transport error
+translation in one place (`_request`) so a bad token or 404 surfaces a teaching message, not a raw
+traceback (踩坑 #37).
+
+### Transitive Dependencies
+Runtime deps: pyvmomi, httpx, typer, rich, pyyaml, python-dotenv, mcp, and `vmware-policy` (the family's
+shared audit/policy/sanitize harness). No urllib3, no requests.
+
+## Static Analysis
+```bash
+uvx bandit -r vmware_privateai/     # target: 0 Medium+ issues
+```
+
+## Supported Versions
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | ✅ (beta) |

vmware_privateai-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vmware-privateai"
+version = "1.0.0"
+description = "VMware Private AI Foundation with NVIDIA ops — GPU inventory, vGPU/DirectPath profiles, utilization, model-serving (MCP + CLI)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Wei Zhou", email = "wei-wz.zhou@broadcom.com" }]
+keywords = ["vmware", "vcf", "gpu", "nvidia", "vgpu", "private-ai", "mcp", "ai-ops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "pyvmomi>=8.0.3.0,<10.0",
+    "httpx>=0.27,<1.0",
+    "typer>=0.12,<1.0",
+    "rich>=13.0,<15.0",
+    "pyyaml>=6.0,<7.0",
+    "python-dotenv>=1.0,<2.0",
+    "mcp[cli]>=1.10,<2.0",
+    "vmware-policy>=1.8.8,<2.0",
+]
+
+[project.scripts]
+vmware-privateai = "vmware_privateai.cli:app"
+vmware-privateai-mcp = "vmware_privateai.mcp_server.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vmware_privateai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "capability: Capability evals — scored trends, not pass/fail gates. Excluded from the default run. Run with: pytest -m capability",
+]
+addopts = "-m 'not capability'"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<10.0",
+    "pytest-cov>=5.0,<8.0",
+    "ruff>=0.5,<1.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+# 踩坑 #33: MCP-server modules are reflected by FastMCP/Pydantic at import time.
+# Tool-signature annotations must stay `Optional[X]` — the PEP 604 `X | None` form
+# can raise `subclass() arg 1 must be a class` under older interpreters. Never let
+# pyupgrade (UP007/UP045) rewrite them in the reflected files.
+"vmware_privateai/mcp_server/**/*.py" = ["UP007", "UP045"]

vmware_privateai-1.0.0/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.vmware-skills/vmware-privateai",
+  "title": "VMware Private AI (GPU & Model Serving)",
+  "description": "VMware Private AI Foundation with NVIDIA ops: GPU inventory, vGPU/DirectPath profiles, utilization, vGPU assignment, PAIS model serving — 10 MCP tools.",
+  "repository": {
+    "url": "https://github.com/vmware-skills/VMware-PrivateAI",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "vmware-privateai",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

vmware_privateai-1.0.0/skills/vmware-privateai/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: vmware-privateai
+description: >
+  Use this skill whenever the user needs the GPU / AI-infrastructure layer of VMware Private AI
+  Foundation with NVIDIA (PAIF-N) on vSphere 9.x / VCF 9.1: inventory GPU hosts and physical GPU
+  devices, see which VMs consume a vGPU and the profile each holds, read real-time GPU utilization,
+  list the vGPU and DirectPath profile catalog, assign a VM's vGPU profile, and list Private AI
+  Service (PAIS) served models and knowledge bases. Always use this skill for "list GPU hosts",
+  "which VMs are using a vGPU", "GPU utilization", "assign a vGPU profile", "list vGPU profiles",
+  "list served models" when the context is explicitly VMware / vSphere / VCF Private AI / NVIDIA
+  vGPU. Do NOT use for the backing VM's power/snapshot/clone/migrate (use vmware-aiops), read-only
+  vSphere inventory/alarms/host health (use vmware-monitor), or GPU-enabled Tanzu Kubernetes
+  (use vmware-vks). This skill is the GPU lens; vmware-aiops owns the VM lifecycle behind it.
+installer:
+  kind: uv
+  package: vmware-privateai
+allowed-tools:
+  - Bash
+metadata: {"openclaw":{"requires":{"env":["VMWARE_PRIVATEAI_CONFIG"],"bins":["vmware-privateai"],"config":["~/.vmware-privateai/config.yaml"]},"primaryEnv":"VMWARE_PRIVATEAI_CONFIG"}}
+---
+
+# VMware Private AI (Foundation with NVIDIA) — GPU & Model-Serving Ops
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with, endorsed by, or
+> sponsored by VMware, Inc., Broadcom Inc., or NVIDIA Corporation.** "VMware", "vSphere", and "VCF"
+> are trademarks of Broadcom; "NVIDIA" and "vGPU" are trademarks of NVIDIA. Source is publicly
+> auditable under the MIT license.
+
+The GPU / AI-infrastructure lens for the VMware skill family — GPU host & device inventory, vGPU
+consumers, real-time GPU utilization, the vGPU / DirectPath profile catalog, vGPU assignment, and
+**Private AI Service (PAIS)** served models and knowledge bases — over the **vSphere 9.x / VCF 9.1**
+Web Services API (pyVmomi) plus the PAIS REST API.
+
+> **Companion skills**: [vmware-aiops](https://github.com/vmware-skills/VMware-AIops) (the vCenter VMs
+> behind AI workloads — power/snapshot/clone), [vmware-vks](https://github.com/vmware-skills/VMware-VKS)
+> (GPU-enabled Tanzu Kubernetes), [vmware-monitor](https://github.com/vmware-skills/VMware-Monitor)
+> (read-only vSphere health).
+
+> **Status: v1.0.0 (beta).** Skill #15 of the family; independent 1.x version line. Every API path is
+> verified against official Broadcom/NVIDIA sources before use (`tests/eval/spec/privateai_endpoints.py`)
+> — no endpoints written from memory. GET-response *field names* and the exact PAIS paths are
+> defensive and pending validation against live 9.x hardware (see Troubleshooting). Governed by the
+> family harness (audit + policy + teaching errors); read-vs-write authorization is delegated to the
+> vCenter service account's RBAC role.
+
+## What This Skill Does
+
+| Category | Tools | Count | Read/Write |
+|----------|-------|:-----:|:----------:|
+| **GPU inventory** | host list/get, device list, vGPU consumer list | 4 | 4 R |
+| **GPU utilization** | real-time per-vGPU-VM utilization (gpu %, mem %, temp) | 1 | 1 R |
+| **Profile catalog** | vGPU profile list, DirectPath profile list | 2 | 2 R |
+| **vGPU assignment** | set a VM's vGPU profile (VM must be powered off) | 1 | 1 W |
+| **Private AI Service** | served-model list, knowledge-base list | 2 | 2 R |
+
+**10 MCP tools (9 read / 1 write).** Reads are strictly non-destructive. The single write
+(`vgpu_assign`) previews its blast radius, refuses a powered-on VM, never powers a VM off itself, is
+double-confirmed at the CLI, and is audit-logged.
+
+## Quick Install
+
+```bash
+uv tool install vmware-privateai
+vmware-privateai version
+vmware-privateai gpu host-list        # first read — lists hosts that have a GPU
+```
+
+Config lives in `~/.vmware-privateai/config.yaml` (targets + optional `pais:` section); passwords and
+the PAIS bearer token live in `~/.vmware-privateai/.env` (chmod 600). See `references/setup-guide.md`.
+
+## When to Use This Skill
+
+Use vmware-privateai for the **GPU / AI-infrastructure layer**: which hosts and physical devices have
+GPUs, which VMs hold a vGPU and what profile, real-time GPU utilization, the assignable vGPU /
+DirectPath profile catalog, changing a VM's vGPU profile, and the models / knowledge bases served by
+Private AI Service — when the context is explicitly VMware / vSphere / VCF Private AI / NVIDIA vGPU.
+
+**Do NOT use when**: the task is the backing VM's lifecycle — power on/off, snapshot, clone, migrate,
+reconfigure CPU/RAM (→ **vmware-aiops**); read-only vSphere inventory, alarms, or host health
+(→ **vmware-monitor**); or GPU-enabled Tanzu Kubernetes / Supervisor namespaces (→ **vmware-vks**).
+`vgpu_assign` deliberately does **not** power the VM off — that is vmware-aiops's job, kept separate
+so this skill's blast radius stays "one VM, when it is already off".
+
+## Related Skills — Skill Routing
+
+| The user wants… | Skill |
+|-----------------|-------|
+| Inventory GPUs / vGPU consumers / GPU utilization / assign a vGPU profile | **vmware-privateai** (this) |
+| List PAIS served models / knowledge bases | **vmware-privateai** (this) |
+| Power off / snapshot / clone / migrate the backing vCenter VM | vmware-aiops |
+| Read-only vSphere inventory / alarms / host health | vmware-monitor |
+| GPU-enabled Tanzu Kubernetes clusters / namespaces | vmware-vks |
+| Multi-step GPU workflow with approval + rollback | vmware-pilot |
+
+## Common Workflows
+
+**1. Find an idle GPU and reassign a VM's vGPU profile.**
+```
+vmware-privateai gpu device-list --vendor NVIDIA     # find GPUs; vm_count 0 = idle
+vmware-privateai gpu consumer-list                   # who holds a vGPU, and which profile
+vmware-privateai vgpu profile-list --host esx-07     # profiles that host can hand a VM
+vmware-privateai gpu vgpu-assign fin-train-01 grid_a100-4c --dry-run   # preview blast radius
+# power the VM off with vmware-aiops, THEN:
+vmware-privateai gpu vgpu-assign fin-train-01 grid_a100-4c             # double-confirm + audit
+```
+*Failure branch*: if `vgpu-assign` (confirm) refuses with "VM is powered on — a vGPU change needs the
+VM powered off", run `vmware-aiops vm_power_off 'fin-train-01'` first, then re-run. If it fails with
+"profile not offered by the VM's host / GPU lacks free framebuffer", run
+`vmware-privateai gpu host-get <that VM's host>` to see the valid profiles and free capacity.
+
+**2. Triage GPU utilization across the estate.**
+```
+vmware-privateai gpu utilization --top 10            # busiest vGPU VMs first
+vmware-privateai gpu host-list --vendor NVIDIA       # which hosts carry the load
+```
+*Failure branch*: a VM showing `metrics unavailable (no host driver?)` is not an error — the NVIDIA
+host GPU driver is not exposing counters for it (`metrics_available:false`). Deep per-SM / per-process
+/ MIG-slice telemetry is **not** available via vSphere; use NVIDIA DCGM on the host for that.
+
+**3. See what Private AI Service is serving.**
+```
+vmware-privateai pais model-list                     # OpenAI-compatible /models
+vmware-privateai pais kb-list                         # RAG knowledge bases
+```
+*Failure branch*: HTTP 404 usually means a base-URL mismatch, not a bug — the `/api/v1` PAIS path
+prefix is deployment-specific and unconfirmed (beta). Check `pais.endpoint` in config.yaml. HTTP
+401/403 means the bearer token in `VMWARE_PRIVATEAI_PAIS_TOKEN` is expired or lacks scope — obtain a
+fresh token from your Identity Provider, re-export it, and retry.
+
+## Usage Mode
+
+- **CLI** — interactive inventory / triage, scripting, small or local models (lower context cost).
+- **MCP** — agent-driven operations with structured JSON; run `vmware-privateai mcp` (an installed
+  console script, so no `uvx` network re-resolve — works through enterprise TLS proxies, 踩坑 #25).
+
+## MCP Tools (10 — 9 read, 1 write)
+
+| Category | Tools | R/W |
+|----------|-------|:---:|
+| GPU inventory | `gpu_host_list`, `gpu_host_get`, `gpu_device_list`, `gpu_consumer_list` | Read |
+| GPU utilization | `gpu_utilization` | Read |
+| Profile catalog | `vgpu_profile_list`, `directpath_profile_list` | Read |
+| Private AI Service | `pais_model_list`, `pais_knowledge_base_list` | Read |
+| vGPU assignment | `vgpu_assign` | Write |
+
+**List envelope**: every `*_list` tool returns `{items, returned, limit, offset, total, truncated, hint}`
+— read rows from `items` and check `truncated` before concluding a listing is complete; empty `items`
+with `truncated:false` means checked-and-none, not a failure. Lists paginate at `limit=50`; filter with
+the tool's `name`/`vendor`/`host`/`profile`/`vm` arguments rather than paging the whole estate.
+
+**Write safety (normative)**: `vgpu_assign` with `confirm=false` (the default) previews only —
+current profile, target profile, power state, and that a power-off is required — without acting.
+`confirm=true` applies it, but refuses a powered-on VM with a teaching error. It **never powers the VM
+off itself**, waits for the real ReconfigVM task outcome (never a premature "ok"), and audits every
+applied change to `~/.vmware/audit.db`.
+
+## CLI Quick Reference
+
+```bash
+vmware-privateai gpu host-list [--name N] [--vendor V]       # hosts with a GPU
+vmware-privateai gpu host-get <host>                          # full per-GPU detail
+vmware-privateai gpu device-list [--host H] [--vendor V]     # physical GPUs (vm_count 0 = idle)
+vmware-privateai gpu consumer-list [--profile P] [--vm V]    # VMs holding a vGPU + profile
+vmware-privateai gpu utilization [--vm V] [--top N]          # real-time GPU %, mem %, temp
+vmware-privateai gpu vgpu-assign <vm> <profile> [--dry-run]  # WRITE — VM must be off; double-confirm
+vmware-privateai vgpu profile-list [--host H] [--model M]    # vGPU profile catalog
+vmware-privateai vgpu directpath-list [--vendor V]           # DirectPath profiles (vSphere 9.0+)
+vmware-privateai pais model-list [--name N]                  # PAIS served models
+vmware-privateai pais kb-list [--name N]                     # PAIS knowledge bases
+```
+Full list: `references/cli-reference.md`. Per-tool response-token estimates: `references/capabilities.md`.
+
+## Troubleshooting
+
+- **`Password not found for target '<t>'. Set environment variable VMWARE_PRIVATEAI_<T>_PASSWORD`** —
+  add that line to `~/.vmware-privateai/.env` and `chmod 600` it, or export it (from a secret manager).
+  The `<T>` is the target name upper-cased with `-`→`_`.
+- **`TLS verification failed for target '<t>'`** — for a self-signed lab set `verify_ssl: false` for
+  that target in `config.yaml`; otherwise install the vCenter CA on this host.
+- **`gpu host-list` returns nothing on a cluster you know has GPUs** — only `shared` / `direct` /
+  `sharedDirect` graphics types count as compute GPUs (the plain host framebuffer is excluded). If real
+  9.x hardware surfaces a GPU under an unexpected type, that is a beta known-limitation — file an issue
+  with the raw `gpu host-get` output so the projection can be widened.
+- **`gpu utilization` shows a VM with `metrics unavailable`** — the NVIDIA host GPU driver is not
+  exposing counters for it (not an error). Note the `gpu.*` perf counters may report at host level on
+  some builds — verify the entity type on real hardware (beta caveat).
+- **`directpath-list` errors with "needs vCenter 9.0+"** — DirectPathProfileManager is new in vSphere
+  9.0; on 8.x use `vgpu profile-list` instead (the error routes you there, not an empty list).
+- **PAIS 404 / non-JSON response** — the `/api/v1` prefix is deployment-specific and unconfirmed;
+  check `pais.endpoint` (a proxy or login page returns non-JSON). PAIS 401/403 → refresh the bearer
+  token in `VMWARE_PRIVATEAI_PAIS_TOKEN`.
+
+## Audit & Safety
+
+1. **Source Code** — https://github.com/vmware-skills/VMware-PrivateAI (MIT).
+2. **Config File Contents** — `config.yaml` holds target host/username/port and the `pais.endpoint`
+   only; passwords and the PAIS bearer token live in `~/.vmware-privateai/.env` (0600, obfuscated to
+   `b64:` at rest — obfuscation, not encryption).
+3. **Webhook Data Scope** — none. This skill makes no outbound calls except to the configured
+   vCenter/ESXi targets and PAIS endpoint.
+4. **TLS Verification** — on by default; `verify_ssl: false` is per-target (and `pais.verify_ssl`) and
+   only for self-signed labs.
+5. **Prompt Injection Protection** — all vSphere-supplied and PAIS-supplied text (device/vendor/VM/
+   profile names, PAIS model ids, knowledge-base descriptions) passes through `vmware_policy.sanitize()`
+   (truncation ≤500 chars + C0/C1 control-char stripping); a KB description is the highest-value
+   injection surface here.
+6. **Least Privilege** — read-vs-write authorization is the vCenter role's job: a read-only service
+   account refuses `vgpu_assign`'s ReconfigVM at vCenter, un-bypassably. All writes are recorded in
+   `~/.vmware/audit.db`. See `references/setup-guide.md`.
+
+## License
+
+MIT