inference-aiops 0.1.0__tar.gz

inference_aiops-0.1.0/.gitignore

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

inference_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to inference-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for GPU inference clusters (vLLM + Ray
+Serve / Ray Jobs) with a bundled governance harness. **Mock-validated only — not
+yet verified against a live cluster.**
+
+### Added
+
+- **30 MCP tools** (16 read, 14 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **Metrics & RCA** — `request_metrics` (TTFT/TPOT/e2e latency + token
+    totals), `queue_depth` (running vs waiting backpressure), `kv_cache_stats`
+    (KV utilisation, prefix-cache hit rate, preemptions), and the flagship
+    correlators `diagnose_latency_spike` and `diagnose_low_utilization` (fold
+    queue depth + KV-cache pressure + prefix-cache locality into a ranked cause
+    plus the specific knob to turn).
+  - **Ray Serve** — reads `serve_deployment_list`, `deployment_status`,
+    `replica_list`, `autoscale_config_get`; writes `scale_replicas_up` (med,
+    undo), `scale_replicas_down` (high, dry-run, undo), `scale_to_zero` (high,
+    dry-run, undo), `autoscale_config_update` (med, undo), `drain_replica`
+    (high, dry-run, graceful — finishes in-flight requests).
+  - **Models / vLLM** — `model_list`, `model_info` (read); `lora_load` (med),
+    `lora_unload` (high, dry-run), `model_hot_swap` (high, dry-run — Sleep-Mode
+    base swap, captures the prior model).
+  - **Ray cluster / jobs / GPU** — `ray_cluster_resources` (CPU/GPU alloc),
+    `ray_dashboard_status`, `ray_job_list`, `gpu_utilization` (per-node) as
+    reads; `ray_job_cancel` (med) and `replica_restart` (high, dry-run) as writes.
+  - **Deploy lifecycle** — `model_deploy` (med), `model_undeploy` (high,
+    dry-run), `deployment_redeploy` (high, dry-run), `routing_policy_update`
+    (med, undo — prefix-aware / session-affinity routing to fix cache locality).
+  - **Cost** — `cost_per_token` (deterministic $/1M tokens from throughput ×
+    GPU $/hr).
+- **Prometheus-native metrics** — parses vLLM's `/metrics` endpoint directly; no
+  Prometheus server required.
+- **Optional encrypted secret store** — a bearer token is optional (many stacks
+  run open); when required it is stored encrypted in
+  `~/.inference-aiops/secrets.enc` (Fernet + scrypt), never plaintext on disk.
+  Legacy `INFERENCE_<TARGET>_TOKEN` env var honoured as a fallback.
+- **CLI** (`inference-aiops`) — `init` wizard, `overview`, `serve`
+  (list/status/scale/scale-to-zero), `metrics` (requests/queue/diagnose),
+  `secret` management, `mcp`, and a `doctor` that probes the Ray dashboard and
+  vLLM independently.
+- **Connection layer** over the Ray dashboard (Serve + Jobs) and the vLLM
+  services with centralised teaching error translation.
+
+### Known limitations
+
+- Preview / mock-only: validated against mocked vLLM `/metrics`, vLLM OpenAI
+  API, and Ray dashboard responses; needs live verification.
+- Unverified against real hardware / topology: multi-GPU tensor-parallel /
+  pipeline-parallel deployments, real GPU thermal/throttle telemetry, and
+  multi-node drain / node-reboot orchestration.

inference_aiops-0.1.0/LICENSE

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

inference_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: inference-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for GPU inference clusters (vLLM + Ray Serve/Jobs): latency/utilization RCA, replica scaling, drain, model lifecycle, and destructive-op guardrails with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/inference-aiops -->
+
+# Inference AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the vLLM or Ray projects or any inference-serving vendor.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **GPU inference clusters** — **vLLM** (OpenAI API + Prometheus
+`/metrics`) and **Ray Serve / Ray Jobs** (Ray dashboard) — with a **built-in
+governance harness**: unified audit log, policy engine, token/runaway budget
+guard, undo-token recording, and graduated-autonomy risk tiers. It parses
+vLLM's Prometheus `/metrics` directly (no Prometheus server required) and probes
+the Ray dashboard independently. A bearer token is **optional** (many stacks run
+open). **Preview — mock-validated only, not yet verified against a live cluster.**
+
+## What it does
+
+The flagship value is **root-cause analysis**, wrapped in guarded reads and writes:
+
+- **`diagnose_latency_spike`** (flagship RCA) — when TTFT/TPOT/e2e latency
+  climbs, it correlates **queue depth** (running vs waiting), **KV-cache
+  pressure / preemptions**, and **prefix-cache locality** into a *ranked* cause
+  plus the **specific knob to turn** (add replicas, raise `max-num-seqs`, fix
+  routing, enlarge KV cache). Every flag is a number, not a black-box verdict.
+- **`diagnose_low_utilization`** — the inverse: idle GPUs, over-provisioned
+  replicas, or routing that strands a cache-warm replica → what to scale down.
+- **Prometheus-native** — reads vLLM's `/metrics` endpoint directly; no
+  Prometheus/Grafana deployment needed.
+- **Governance-grade** — the **first governance-grade entrant** in this niche:
+  audit + budget + risk-tier approval + undo-token + prompt-injection sanitize,
+  with **dry-run + double-confirm** on the fragile prod ops (scale-down,
+  scale-to-zero, drain, redeploy, hot-swap) the community reports as dangerous.
+- **Laptop self-test** — ~80% of the tool self-tests free: vLLM on a single GPU
+  or CPU-mock + Ray in one local container (`ray start --head`).
+
+## Capability matrix (30 MCP tools)
+
+| Group | Tools | Count | R/W (risk) |
+|-------|-------|:-----:|:-----------|
+| **Metrics & RCA** | `request_metrics`, `queue_depth`, `kv_cache_stats`, `diagnose_latency_spike`, `diagnose_low_utilization` | 5 | read |
+| **Ray Serve (read)** | `serve_deployment_list`, `deployment_status`, `replica_list`, `autoscale_config_get` | 4 | read |
+| **Ray Serve (write)** | `scale_replicas_up`, `scale_replicas_down`, `scale_to_zero`, `autoscale_config_update`, `drain_replica` | 5 | write (med / **high**) |
+| **Models / vLLM** | `model_list`, `model_info`, `lora_load`, `lora_unload`, `model_hot_swap` | 5 | read + write (med / **high**) |
+| **Ray cluster / jobs / GPU** | `ray_cluster_resources`, `ray_dashboard_status`, `ray_job_list`, `gpu_utilization`, `ray_job_cancel`, `replica_restart` | 6 | read + write (med / **high**) |
+| **Deploy lifecycle** | `model_deploy`, `model_undeploy`, `deployment_redeploy`, `routing_policy_update` | 4 | write (med / **high**) |
+| **Cost** | `cost_per_token` | 1 | read |
+
+**16 read, 14 write.** High-risk writes (`scale_replicas_down`,
+`scale_to_zero`, `drain_replica`, `lora_unload`, `model_hot_swap`,
+`replica_restart`, `model_undeploy`, `deployment_redeploy`) all support
+`dry_run` + double-confirm; reversible writes record an undo descriptor.
+
+## Install
+
+```bash
+uv tool install inference-aiops          # or: pipx install inference-aiops
+```
+
+## Quick start
+
+```bash
+inference-aiops init                     # wizard: host + ray_port + vllm_port + scheme
+inference-aiops doctor                   # probes BOTH the Ray dashboard and vLLM independently
+inference-aiops overview                 # deployments + total replicas + queue backpressure
+inference-aiops metrics diagnose         # why is inference slow? ranked RCA + the knob to turn
+inference-aiops serve list               # Ray Serve deployments + replica counts
+```
+
+Run as an MCP server (stdio) for the full 30-tool surface:
+
+```bash
+export INFERENCE_AIOPS_MASTER_PASSWORD=...   # only if a bearer token is stored
+inference-aiops mcp
+```
+
+The CLI is a convenience subset (`init`, `overview`, `serve …`, `metrics …`,
+`secret …`, `doctor`, `mcp`); the full 30 tools are exposed via the MCP server.
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier,
+  approver, rationale) logged to `~/.inference-aiops/audit.db` (relocatable via
+  `INFERENCE_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker on
+  tight poll/retry loops.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named
+  approver (`INFERENCE_AUDIT_APPROVED_BY` / `INFERENCE_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes (scale, autoscale-config, routing,
+  hot-swap, LoRA load) record an inverse descriptor.
+
+## Supported scope + limitations
+
+**Preview / mock-only.** All behaviour is validated against mocked vLLM
+`/metrics`, vLLM OpenAI API, and Ray dashboard responses. **~80% of the tool
+self-tests on a laptop** — vLLM on a single GPU or CPU-mock plus a local
+one-node Ray head. Not yet verified against a live production cluster.
+
+Unverified against real hardware / topology:
+
+- multi-GPU **tensor-parallel / pipeline-parallel** deployments,
+- real GPU **thermal / throttle** telemetry (utilisation is best-effort from
+  the Ray dashboard's `/api/nodes`),
+- **multi-node drain** and node-reboot orchestration.
+
+The fastest live check is `inference-aiops doctor`.
+
+## Missing a capability?
+
+This is the GPU-inference member of the AIops-tools family (governed AI-ops with
+audit + budget + undo + risk tiers). If a vLLM or Ray capability you need is
+missing, or your stack speaks a dialect these tools don't yet handle — open an
+issue or a PR. Contributions welcome.

inference_aiops-0.1.0/README.md

@@ -0,0 +1,113 @@
+<!-- mcp-name: io.github.AIops-tools/inference-aiops -->
+
+# Inference AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the vLLM or Ray projects or any inference-serving vendor.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **GPU inference clusters** — **vLLM** (OpenAI API + Prometheus
+`/metrics`) and **Ray Serve / Ray Jobs** (Ray dashboard) — with a **built-in
+governance harness**: unified audit log, policy engine, token/runaway budget
+guard, undo-token recording, and graduated-autonomy risk tiers. It parses
+vLLM's Prometheus `/metrics` directly (no Prometheus server required) and probes
+the Ray dashboard independently. A bearer token is **optional** (many stacks run
+open). **Preview — mock-validated only, not yet verified against a live cluster.**
+
+## What it does
+
+The flagship value is **root-cause analysis**, wrapped in guarded reads and writes:
+
+- **`diagnose_latency_spike`** (flagship RCA) — when TTFT/TPOT/e2e latency
+  climbs, it correlates **queue depth** (running vs waiting), **KV-cache
+  pressure / preemptions**, and **prefix-cache locality** into a *ranked* cause
+  plus the **specific knob to turn** (add replicas, raise `max-num-seqs`, fix
+  routing, enlarge KV cache). Every flag is a number, not a black-box verdict.
+- **`diagnose_low_utilization`** — the inverse: idle GPUs, over-provisioned
+  replicas, or routing that strands a cache-warm replica → what to scale down.
+- **Prometheus-native** — reads vLLM's `/metrics` endpoint directly; no
+  Prometheus/Grafana deployment needed.
+- **Governance-grade** — the **first governance-grade entrant** in this niche:
+  audit + budget + risk-tier approval + undo-token + prompt-injection sanitize,
+  with **dry-run + double-confirm** on the fragile prod ops (scale-down,
+  scale-to-zero, drain, redeploy, hot-swap) the community reports as dangerous.
+- **Laptop self-test** — ~80% of the tool self-tests free: vLLM on a single GPU
+  or CPU-mock + Ray in one local container (`ray start --head`).
+
+## Capability matrix (30 MCP tools)
+
+| Group | Tools | Count | R/W (risk) |
+|-------|-------|:-----:|:-----------|
+| **Metrics & RCA** | `request_metrics`, `queue_depth`, `kv_cache_stats`, `diagnose_latency_spike`, `diagnose_low_utilization` | 5 | read |
+| **Ray Serve (read)** | `serve_deployment_list`, `deployment_status`, `replica_list`, `autoscale_config_get` | 4 | read |
+| **Ray Serve (write)** | `scale_replicas_up`, `scale_replicas_down`, `scale_to_zero`, `autoscale_config_update`, `drain_replica` | 5 | write (med / **high**) |
+| **Models / vLLM** | `model_list`, `model_info`, `lora_load`, `lora_unload`, `model_hot_swap` | 5 | read + write (med / **high**) |
+| **Ray cluster / jobs / GPU** | `ray_cluster_resources`, `ray_dashboard_status`, `ray_job_list`, `gpu_utilization`, `ray_job_cancel`, `replica_restart` | 6 | read + write (med / **high**) |
+| **Deploy lifecycle** | `model_deploy`, `model_undeploy`, `deployment_redeploy`, `routing_policy_update` | 4 | write (med / **high**) |
+| **Cost** | `cost_per_token` | 1 | read |
+
+**16 read, 14 write.** High-risk writes (`scale_replicas_down`,
+`scale_to_zero`, `drain_replica`, `lora_unload`, `model_hot_swap`,
+`replica_restart`, `model_undeploy`, `deployment_redeploy`) all support
+`dry_run` + double-confirm; reversible writes record an undo descriptor.
+
+## Install
+
+```bash
+uv tool install inference-aiops          # or: pipx install inference-aiops
+```
+
+## Quick start
+
+```bash
+inference-aiops init                     # wizard: host + ray_port + vllm_port + scheme
+inference-aiops doctor                   # probes BOTH the Ray dashboard and vLLM independently
+inference-aiops overview                 # deployments + total replicas + queue backpressure
+inference-aiops metrics diagnose         # why is inference slow? ranked RCA + the knob to turn
+inference-aiops serve list               # Ray Serve deployments + replica counts
+```
+
+Run as an MCP server (stdio) for the full 30-tool surface:
+
+```bash
+export INFERENCE_AIOPS_MASTER_PASSWORD=...   # only if a bearer token is stored
+inference-aiops mcp
+```
+
+The CLI is a convenience subset (`init`, `overview`, `serve …`, `metrics …`,
+`secret …`, `doctor`, `mcp`); the full 30 tools are exposed via the MCP server.
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier,
+  approver, rationale) logged to `~/.inference-aiops/audit.db` (relocatable via
+  `INFERENCE_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker on
+  tight poll/retry loops.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named
+  approver (`INFERENCE_AUDIT_APPROVED_BY` / `INFERENCE_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes (scale, autoscale-config, routing,
+  hot-swap, LoRA load) record an inverse descriptor.
+
+## Supported scope + limitations
+
+**Preview / mock-only.** All behaviour is validated against mocked vLLM
+`/metrics`, vLLM OpenAI API, and Ray dashboard responses. **~80% of the tool
+self-tests on a laptop** — vLLM on a single GPU or CPU-mock plus a local
+one-node Ray head. Not yet verified against a live production cluster.
+
+Unverified against real hardware / topology:
+
+- multi-GPU **tensor-parallel / pipeline-parallel** deployments,
+- real GPU **thermal / throttle** telemetry (utilisation is best-effort from
+  the Ray dashboard's `/api/nodes`),
+- **multi-node drain** and node-reboot orchestration.
+
+The fastest live check is `inference-aiops doctor`.
+
+## Missing a capability?
+
+This is the GPU-inference member of the AIops-tools family (governed AI-ops with
+audit + budget + undo + risk tiers). If a vLLM or Ray capability you need is
+missing, or your stack speaks a dialect these tools don't yet handle — open an
+issue or a PR. Contributions welcome.

inference_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,55 @@
+# Inference AIops v0.1.0 — preview
+
+Governed AI-ops for **GPU inference clusters** — **vLLM** (OpenAI API +
+Prometheus `/metrics`) and **Ray Serve / Ray Jobs** (Ray dashboard) — for AI
+agents, with a built-in governance harness (audit, policy, token/runaway budget,
+undo-token recording, graduated risk tiers) and an optional encrypted credential
+store. Standalone — no external skill-family dependency.
+
+> **Preview / mock-only.** All behaviour is validated against mocked vLLM
+> `/metrics`, vLLM OpenAI API, and Ray dashboard responses; it has not been run
+> against a live cluster. The fastest live check is `inference-aiops doctor`.
+
+## Highlights
+
+- **30 MCP tools** (16 read, 14 write), every one wrapped with `@governed_tool`.
+  - **Metrics & RCA** (read): `request_metrics` (TTFT/TPOT/e2e + token totals),
+    `queue_depth` (running vs waiting backpressure), `kv_cache_stats` (KV util,
+    prefix-cache hit rate, preemptions), and the flagship correlators
+    `diagnose_latency_spike` / `diagnose_low_utilization`.
+  - **Ray Serve**: reads (`serve_deployment_list`, `deployment_status`,
+    `replica_list`, `autoscale_config_get`) + guarded writes (`scale_replicas_up`,
+    `scale_replicas_down`, `scale_to_zero`, `autoscale_config_update`,
+    `drain_replica`).
+  - **Models / vLLM**: `model_list`, `model_info`, `lora_load`, `lora_unload`,
+    `model_hot_swap` (Sleep-Mode base swap, captures prior model).
+  - **Ray cluster / jobs / GPU**: `ray_cluster_resources`, `ray_dashboard_status`,
+    `ray_job_list`, `gpu_utilization`, `ray_job_cancel`, `replica_restart`.
+  - **Deploy lifecycle**: `model_deploy`, `model_undeploy`, `deployment_redeploy`,
+    `routing_policy_update` (prefix-aware / session-affinity routing).
+  - **Cost**: `cost_per_token` (deterministic $/1M tokens from throughput × GPU $/hr).
+- **Prometheus-native** — parses vLLM's `/metrics` directly; no Prometheus
+  server required.
+- **Safety on the fragile ops** — `scale_replicas_down`, `scale_to_zero`,
+  `drain_replica`, `lora_unload`, `model_hot_swap`, `replica_restart`,
+  `model_undeploy`, `deployment_redeploy` are high-risk with `dry_run` +
+  double-confirm; reversible writes record an undo descriptor.
+- **Optional-token auth** — a bearer token is optional (many stacks run open);
+  when required it is stored **encrypted** (`~/.inference-aiops/secrets.enc`,
+  Fernet + scrypt) — never plaintext on disk.
+- **CLI** with an `init` onboarding wizard, `secret` management, and a `doctor`
+  that probes the Ray dashboard and vLLM independently.
+
+## Install
+
+```bash
+uv tool install inference-aiops
+inference-aiops init
+inference-aiops doctor
+```
+
+## Caveats
+
+- Preview / mock-only: validated against mocked responses; needs live verification.
+- Unverified against real hardware: multi-GPU tensor/pipeline-parallel
+  deployments, real GPU thermal/throttle telemetry, and multi-node drain.

inference_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,79 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by the vLLM or Ray projects.** Product and trademark names belong to
+their owners. Source is publicly auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Inference-AIops](https://github.com/AIops-tools/Inference-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- A bearer token is **optional** (many on-prem inference stacks run open). When
+  used, per-target tokens live **encrypted** in `~/.inference-aiops/secrets.enc`
+  (Fernet/AES-128 + scrypt-derived key; chmod 600), never in `config.yaml` and
+  never in source. The master password is never stored — only a per-store random
+  salt and the ciphertext are on disk.
+- A legacy plaintext env var `INFERENCE_<TARGET_NAME_UPPER>_TOKEN` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `inference-aiops secret migrate`).
+- When present, the token is sent as an `Authorization: Bearer` header and held
+  only in memory; it is never logged or echoed. The config file holds only host,
+  Ray/vLLM ports, scheme, and TLS settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`inference_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.inference-aiops/`
+  (relocatable via `INFERENCE_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`INFERENCE_MAX_TOOL_CALLS` /
+  `INFERENCE_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption (e.g. polling a slow
+  session).
+- **Graduated risk tiers** — `~/.inference-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the BEFORE state and
+  record an inverse descriptor (e.g. a scale op → restore the prior replica
+  count, `autoscale_config_update` → restore prior bounds, `routing_policy_update`
+  → restore the prior policy) so the change can be rolled back.
+
+### State-Changing Operations
+Destructive/traffic-affecting writes — `scale_replicas_down`, `scale_to_zero`,
+`drain_replica`, `lora_unload`, `model_hot_swap`, `model_undeploy`,
+`deployment_redeploy`, `replica_restart` — are `risk_level=high`, accept a
+`dry_run` preview, and (under `risk_tiers`) require a recorded approver
+(`INFERENCE_AUDIT_APPROVED_BY` + `INFERENCE_AUDIT_RATIONALE`). The CLI
+additionally double-confirms `serve scale-to-zero` and supports `--dry-run`.
+Reversible medium/low writes capture before-state and record an undo token.
+
+### SSL/TLS Verification
+`verify_ssl` is off by default (inference stacks commonly serve plain HTTP on a
+trusted network); set `scheme: https` + `verify_ssl: true` for TLS endpoints.
+
+### Prompt-Injection Protection
+All server-returned text (model ids, deployment/replica names, job entrypoints,
+Prometheus label values) is passed through a `sanitize()` truncate +
+control-character strip before reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured Ray dashboard
+and vLLM endpoints. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r inference_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

inference_aiops-0.1.0/inference_aiops/__init__.py

@@ -0,0 +1,9 @@
+"""inference-aiops — governed Inference SCALE operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``inference_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage.
+"""
+
+__version__ = "0.1.0"

inference_aiops-0.1.0/inference_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for inference-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``inference-aiops = "inference_aiops.cli:app"`` works unchanged.
+"""
+
+from inference_aiops.cli._root import app
+
+__all__ = ["app"]

inference_aiops-0.1.0/inference_aiops/cli/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for inference-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from inference_aiops.connection import InferenceApiError
+
+    return (InferenceApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None):
+    """Return a (conn, config) tuple for the given target."""
+    from inference_aiops.config import load_config
+    from inference_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

inference_aiops-0.1.0/inference_aiops/cli/_root.py

@@ -0,0 +1,57 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from inference_aiops.cli._common import cli_errors
+from inference_aiops.cli.doctor import doctor_cmd
+from inference_aiops.cli.init import init_cmd
+from inference_aiops.cli.metrics import metrics_app
+from inference_aiops.cli.overview import overview_cmd
+from inference_aiops.cli.secret import secret_app
+from inference_aiops.cli.serve import serve_app
+
+app = typer.Typer(
+    name="inference-aiops",
+    help="Governed AI-ops for GPU inference (vLLM + Ray Serve): metrics/RCA, "
+    "scaling, drain, models, jobs.",
+    no_args_is_help=True,
+)
+
+app.add_typer(serve_app, name="serve")
+app.add_typer(metrics_app, name="metrics")
+app.add_typer(secret_app, name="secret")
+app.command("init")(init_cmd)
+app.command("overview")(overview_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        inference-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: inference-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force inference-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

inference_aiops-0.1.0/inference_aiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from inference_aiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_auth: Annotated[
+        bool, typer.Option("--skip-auth", help="Skip connectivity check (faster)")
+    ] = False,
+) -> None:
+    """Check environment, config, secrets, and connectivity."""
+    from inference_aiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_auth=skip_auth))