gpu-container 0.1.0__tar.gz

gpu_container-0.1.0/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitignore
+.pytest_cache
+**/__pycache__
+*.pyc
+docs
+tests
+KICKOFF-*.md
+*.egg-info
+profile*.json

gpu_container-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+# Paths-gated per the org GitHub Actions rules: only run when code, tests, packaging,
+# the verify script, or the workflow itself change. workflow_dispatch is the manual fallback.
+on:
+  push:
+    paths:
+      - 'pyproject.toml'
+      - 'gpu_container/**'
+      - 'tests/**'
+      - 'scripts/**'
+      - '.github/workflows/**'
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'gpu_container/**'
+      - 'tests/**'
+      - 'scripts/**'
+      - '.github/workflows/**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,host]"
+      # The verify script runs the test suite + a CLI smoke of all five commands in one command (gate D1).
+      - run: python scripts/verify.py
+
+  deps:
+    # Dependency scanning (shipcheck gate D3). The core package has zero required deps;
+    # this scans the optional [host] extras (psutil, numpy) + the build toolchain.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[host]" pip-audit
+      - run: pip-audit

gpu_container-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install site dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

gpu_container-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,216 @@
+name: Release
+
+# On a published GitHub Release this:
+#   1. publishes the Python package to PyPI via Trusted Publishing (OIDC, no token),
+#   2. builds PyInstaller binaries for each platform + uploads them (+ checksums) to the release,
+#   3. publishes the `gpu-container` npm launcher via Trusted Publishing,
+#   4. builds + pushes the profiler Docker image to ghcr.io.
+#
+# Org rule: publish workflows fire on `release: published` only. The repo has ci.yml + this
+# release.yml (the org 2-workflow CI/publish pair) + pages.yml (the GitHub-Pages-deploy exception,
+# paths-gated to site/**). The cross-OS binary matrix (macos/windows) is the explicit-request
+# exception to the "1 OS / no macos" rule — the npm launcher distributes platform binaries.
+#
+# First PyPI publish needs a PyPI *pending publisher* (project gpu-container, workflow release.yml,
+# environment "(Any)" — these jobs declare no GH environment). First npm publish needs a placeholder
+# publish + a Trusted Publisher on npmjs.com for `gpu-container` (workflow release.yml).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false # never cancel an in-flight publish
+
+jobs:
+  pypi:
+    name: Publish to PyPI (Trusted Publishing)
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC handshake for PyPI Trusted Publishing — the only auth needed
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Verify the tag matches pyproject version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          echo "tag=${TAG} pyproject=${PKG}"
+          if [ "${TAG}" != "${PKG}" ]; then
+            echo "::error::release tag ${TAG} does not match pyproject version ${PKG}"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        # Trusted Publishing: no token. PEP 740 attestations are on by default (action >= v1.11.0).
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  build-binaries:
+    name: Build binary (${{ matrix.target }})
+    strategy:
+      fail-fast: false # one OS's failure must not cancel the others
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+            ext: ""
+          - os: macos-latest
+            target: darwin-arm64
+            ext: ""
+          - os: windows-latest
+            target: win-x64
+            ext: ".exe"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install 3.12
+      - run: uv venv
+
+      - name: Install gpu-container + PyInstaller
+        # [host] = psutil + numpy (system RAM, CPU-bandwidth probe, the watchdog). pynvml is optional
+        # (the profiler falls back to nvidia-smi); the binary still profiles + plans + watches.
+        run: uv pip install ".[host]" "pyinstaller>=6.9.0"
+
+      - name: Build binary
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          uv run pyinstaller --onefile --name gpu-container --console \
+            --collect-submodules gpu_container \
+            --copy-metadata gpu-container \
+            gpu_container/__main__.py
+          OUTNAME="gpu-container-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          mv "dist/gpu-container${{ matrix.ext }}" "dist/${OUTNAME}"
+          echo "ASSET_NAME=${OUTNAME}" >> "$GITHUB_ENV"
+
+      - name: Smoke-test the binary
+        shell: bash
+        run: dist/${{ env.ASSET_NAME }} --version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/${{ env.ASSET_NAME }}
+
+  release-binaries:
+    name: Upload binaries + checksums to the release
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # upload assets to the release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Generate checksums
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          cd artifacts
+          sha256sum * > "checksums-${VERSION}.txt"
+          cat "checksums-${VERSION}.txt"
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*
+
+  npm:
+    name: Publish npm launcher (Trusted Publishing)
+    needs: release-binaries # the launcher is only useful once the binaries are on the release
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # npm provenance via Sigstore OIDC
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Verify the npm launcher version matches the tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(node -p "require('./npm/package.json').version")
+          echo "tag=${TAG} npm=${PKG}"
+          if [ "${TAG}" != "${PKG}" ]; then
+            echo "::error::release tag ${TAG} does not match npm/package.json version ${PKG}"
+            exit 1
+          fi
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install npm >= 11.5 for OIDC trusted-publishing auth
+        run: |
+          # Node 22's bundled npm 10.9 races on an in-place `npm install -g npm@latest`
+          # (MODULE_NOT_FOUND: promise-retry). Install npm@latest into a sandbox and shadow it.
+          SANDBOX="$HOME/.npm-cli-sandbox"
+          mkdir -p "$SANDBOX"
+          pushd "$SANDBOX" >/dev/null
+          echo '{"name":"npm-cli-sandbox","version":"0.0.0","private":true}' > package.json
+          npm install --no-save --no-audit --no-fund --silent npm@latest
+          popd >/dev/null
+          echo "$SANDBOX/node_modules/.bin" >> "$GITHUB_PATH"
+          "$SANDBOX/node_modules/.bin/npm" --version
+
+      - name: Publish launcher with provenance (OIDC trusted publisher)
+        working-directory: npm
+        run: |
+          npm install --no-save --no-audit --no-fund
+          npm publish --provenance --access public
+
+  docker:
+    name: Build + push Docker image (ghcr)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write # push to ghcr.io
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Compute image tags
+        id: tags
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          IMG="ghcr.io/mcp-tool-shop-org/gpu-container"
+          # Always tag the exact version; only move :latest for a non-prerelease (stable) release.
+          {
+            echo "tags<<EOF"
+            echo "${IMG}:${VERSION}"
+            if [ "${{ github.event.release.prerelease }}" != "true" ]; then
+              echo "${IMG}:latest"
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Log in to ghcr
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build + push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.tags.outputs.tags }}

gpu_container-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# --- Node ---
+node_modules/
+npm-debug.log*
+pnpm-debug.log*
+*.tsbuildinfo
+
+# --- Build / dist ---
+dist/
+build/
+out/
+
+# --- Model weights / large artifacts (NEVER commit) ---
+*.gguf
+*.safetensors
+*.bin
+*.pt
+*.pth
+*.onnx
+models/
+weights/
+.cache/
+
+# --- Runtime outputs (profiles + receipts are generated, not committed) ---
+receipts/
+profiles/out/
+*.receipt.json
+profile*.json
+plan*.json
+bench*.json
+receipt*.json
+prof_dry.json
+*.config.json
+*-err.txt
+
+# --- Secrets / env ---
+.env
+.env.*
+!.env.example
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.log
+site/.astro/
+.polyglot-cache.json

gpu_container-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+The full feature set below is built and tested; it becomes `[1.0.0]` at the first release.
+
+### Added
+- **Hardware + model profiler** (`gpu-container-profile`) — measured PCIe H2D/D2H, NVMe sequential + random-QD1, pinnable-RAM ceiling, CPU RAM bandwidth (all measured in-container, `None`-not-guess); closed-form model param-split (expert vs always-resident) and KV growth.
+- **Placement planner** (`gpu-container-plan`) — minimal llama.cpp `--n-cpu-moe N` to fit VRAM, a roofline ceiling **and** a calibrated forecast band, and an honest ship/refuse verdict at the >1 tok/s floor.
+- **Receipt + recalibration loop** (`gpu-container-receipt`) — pairs a `llama-bench` run with the plan's forecast, records realized efficiency / within-band, and writes a calibration point back so the next plan is calibrated. The verifier is a real GPU run, a different mechanism than the planner's math.
+- **Routing de-risk gate** (`gpu-container-concentration`) — scores expert-routing concentration (`hot_frac_for_coverage`, `concentration_score`) from an activation trace or a `llama-imatrix` capture, to decide whether per-expert caching is worth building. Backed by [ADR-0001](docs/decisions/0001-per-expert-cache-build-vs-upstream.md).
+- **Rig-safety watchdog** (`gpu-container-watchdog`) — polls GPU power/temp/VRAM (worst-case across all GPUs) + host memory against thresholds; emits ok/warn/abort (exit 0/5/7). A **supervisor mode** (`run -- <cmd>`) launches a GPU job as a child, polls in parallel, and aborts on a breach via `kill-job` (soft) or `wsl-shutdown` (catastrophic). Peak metrics export to the receipt (`--peaks-out` → `--peaks`) prove a run stayed inside the safe envelope. Shipped `watchdog.example.json`; `mem_source` tags host vs WSL2 VM; `--log` JSONL trajectory.
+- **Docs** — `docs/cli.md` (CLI reference), `docs/quickstart.md` (end-to-end walkthrough), `docs/derisk-concentration.md` (the de-risk methodology), `docs/architecture.md`, `docs/features.md`, `docs/moe-lane-architecture.md`, `docs/feasibility.md`, ADR-0001.
+
+### Fixed
+- Planner emits `-fa on` (current llama.cpp rejects a value-less `-fa`).
+- Receipt: the safety-envelope verdict no longer clobbers the throughput `within_band` verdict (independent fields).
+
+### Notes
+- Runtime support: **llama.cpp** is the integrated backend; the placement math is backend-agnostic and vLLM/Accelerate/ExLlamaV2/TensorRT-LLM are designed targets.
+- Per-expert tiering is gated behind the de-risk gate + the upstream llama.cpp `#20757` mechanism (ADR-0001); the per-layer hot tier ships today.

gpu_container-0.1.0/Dockerfile

@@ -0,0 +1,30 @@
+# gpu-container profiler — runs INSIDE the container, the only honest measurement vantage
+# (docker-knowledge wave-2 hw-measurement). Base = CUDA 12.8 *runtime*: it ships libcudart
+# for the ctypes PCIe bench and targets sm_120 (RTX 5090 / Blackwell). No nvcc needed —
+# cudaMemcpy/cudaHostAlloc are copy-engine ops, not compiled device kernels.
+#
+# Build:  docker build -t gpu-container .
+# Run:    docker run --rm --gpus all -v gpc-bench:/bench gpu-container            # full profile
+#         docker run --rm --gpus all gpu-container --no-bench                     # identity only
+#         docker run --rm --gpus all -v gpc-bench:/bench -v "$PWD":/out \
+#                    gpu-container -o /out/profile.json
+FROM nvidia/cuda:12.8.1-runtime-ubuntu24.04
+
+# fio = NVMe seq + random-QD1 (pulls libaio); python3/pip = the profiler itself.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip fio \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY gpu_container ./gpu_container
+# [gpu]=pynvml (NVML v2 VRAM), [host]=psutil (RAM). Container venv is fine to write into.
+RUN pip3 install --no-cache-dir --break-system-packages ".[gpu,host]"
+
+# The NVMe bench writes here. Mount an ext4-backed volume (named volumes live on the WSL2
+# ext4 vdisk — fast); NEVER a /mnt/<letter> drvfs bind (9p, ~5-10x slower) or the overlay
+# layer (breaks O_DIRECT). The profiler refuses the wrong filesystem rather than mismeasure.
+ENV GPU_CONTAINER_BENCH_DIR=/bench
+VOLUME ["/bench"]
+
+ENTRYPOINT ["python3", "-m", "gpu_container.profiler.cli"]

gpu_container-0.1.0/LICENSE

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

gpu_container-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: gpu-container
+Version: 0.1.0
+Summary: Model-aware inference memory-placement planner for single-GPU rigs — profile, plan, prove.
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gpu,inference,llm,moe,offload,placement,profiler,vram
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: nvidia-ml-py>=12.535.0; extra == 'gpu'
+Provides-Extra: host
+Requires-Dist: numpy>=1.24; extra == 'host'
+Requires-Dist: psutil>=5.9.0; extra == 'host'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/mcp-tool-shop-org/gpu-container/main/assets/logo.png" width="400" alt="gpu-container" />
+
+[![CI](https://github.com/mcp-tool-shop-org/gpu-container/actions/workflows/ci.yml/badge.svg)](https://github.com/mcp-tool-shop-org/gpu-container/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gpu-container)](https://pypi.org/project/gpu-container/)
+[![npm](https://img.shields.io/npm/v/gpu-container)](https://www.npmjs.com/package/gpu-container)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Handbook](https://img.shields.io/badge/handbook-docs-blue)](https://mcp-tool-shop-org.github.io/gpu-container/)
+
+**A GPU-enabled container exposes the device. A model-aware runtime decides what lives in VRAM, pinned RAM, and NVMe.**
+
+</div>
+
+Run the largest useful local model your machine can honestly support, with explicit placement plans, benchmark receipts, and refusal when the plan would thrash.
+
+## Architecture
+
+```
+Windows / WSL2 / Linux host
+  └─ GPU-enabled Docker container
+      └─ Inference runtime
+          ├─ VRAM: hot weights, active layers, activations, KV working set
+          ├─ pinned RAM: CPU-offloaded weights, MoE experts, KV spill/reuse
+          └─ NVMe: mmap shards, disk offload, cold experts, cold KV
+```
+
+## Product Boundary
+
+```
+Docker         = packaging + GPU exposure
+CUDA/runtime   = compute backend
+Planner        = memory law
+Inference engine = execution
+```
+
+## Core Features
+
+1. **Hardware profiler** — Detect VRAM, RAM, GPU type, WSL/native Linux, NVMe speed, CUDA availability
+2. **Model profiler** — Detect dense vs MoE, largest layer, total weights, quantization, KV growth by context length
+3. **Runtime planner** — Generate launch plans for llama.cpp, vLLM, Accelerate, TensorRT-LLM, or DeepSpeed-style offload
+4. **Placement receipt** — Show what is in VRAM, what is in RAM, what is on disk, expected bottleneck, measured tokens/sec
+5. **MoE-specialized path** — Keep always-active layers on GPU, route experts to CPU/RAM, NVMe for cold fallback
+6. **Routing de-risk** — Measure whether a model's MoE routing is skewed enough that a per-expert cache would help, before building for it (`gpu-container-concentration`)
+7. **Rig-safety watchdog** — Poll GPU power/temperature/VRAM + host memory against configurable thresholds; an AI agent or an autonomous loop aborts a run before it endangers the machine (`gpu-container-watchdog`)
+
+## Key Constraint
+
+On Windows/WSL, CUDA Unified Memory oversubscription is **not the path**. CUDA treats Windows/WSL as limited unified-memory support — no fine-grained GPU page-fault migration, no GPU-memory oversubscription beyond physical VRAM. This product is **explicit inference memory placement**, not "Docker VRAM overflow."
+
+## Status
+
+Built and working today: `gpu-container-profile`, `gpu-container-plan`, `gpu-container-receipt` (with the recalibration loop), `gpu-container-concentration` (routing de-risk), and `gpu-container-watchdog` (supervise a GPU job safely). llama.cpp is the integrated backend; the placement math is backend-agnostic. Start with the [quickstart](docs/quickstart.md).
+
+## Privacy & safety
+
+`gpu-container` is a **local, offline tool** — it makes no network calls and collects **no telemetry**, by default or otherwise. It reads GPU metrics (`nvidia-smi` / NVML) and host memory (`psutil`), the model `config.json` you supply, and the JSON files you point it at; it writes only to the output paths you specify. It does **not** read or transmit model weights, credentials, or tokens. Host-level actions (`wsl --shutdown`, `docker stop`, `kill`) run only when you explicitly opt in via the watchdog's `--on-breach`; the defaults never touch your machine beyond the job they supervise. Full policy: [SECURITY.md](SECURITY.md).
+
+## Documentation
+
+- [`docs/quickstart.md`](docs/quickstart.md) — end-to-end walkthrough: profile → plan → launch under the watchdog → receipt → recalibrate
+- [`docs/cli.md`](docs/cli.md) — the five commands: synopsis, flags, exit codes, worked examples
+- [`docs/architecture.md`](docs/architecture.md) — memory-tier model, data flow, MoE expert routing, the recalibration loop
+- [`docs/features.md`](docs/features.md) — the seven core features in depth
+- [`docs/moe-lane-architecture.md`](docs/moe-lane-architecture.md) — the flagship MoE lane in depth
+- [`docs/derisk-concentration.md`](docs/derisk-concentration.md) — the per-expert-cache de-risk gate (routing concentration)
+- [`docs/decisions/0001-per-expert-cache-build-vs-upstream.md`](docs/decisions/0001-per-expert-cache-build-vs-upstream.md) — ADR-0001: consume the cache mechanism, contribute the policy
+- [`docs/constraints.md`](docs/constraints.md) — non-goals + the Windows/WSL CUDA Unified-Memory correction
+- [`docs/prior-art.md`](docs/prior-art.md) — runtimes we orchestrate, and the gap this product fills
+- [`docs/feasibility.md`](docs/feasibility.md) — feasibility assessment, research grounding, and what's confirmed live
+
+---
+
+<div align="center">
+
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> · MIT Licensed
+
+</div>

gpu_container-0.1.0/README.es.md

@@ -0,0 +1,82 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/mcp-tool-shop-org/gpu-container/main/assets/logo.png" width="400" alt="gpu-container" />
+
+[![CI](https://github.com/mcp-tool-shop-org/gpu-container/actions/workflows/ci.yml/badge.svg)](https://github.com/mcp-tool-shop-org/gpu-container/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gpu-container)](https://pypi.org/project/gpu-container/)
+[![npm](https://img.shields.io/npm/v/gpu-container)](https://www.npmjs.com/package/gpu-container)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Handbook](https://img.shields.io/badge/handbook-docs-blue)](https://mcp-tool-shop-org.github.io/gpu-container/)
+
+**Un contenedor habilitado para GPU expone el dispositivo. Un entorno de ejecución consciente del modelo decide qué se almacena en la VRAM, la RAM asignada y la NVMe.**
+
+</div>
+
+Ejecute el modelo local más grande y útil que su máquina pueda soportar de manera realista, con planes de ubicación explícitos, informes de pruebas de rendimiento y rechazo cuando el plan cause problemas.
+
+## Arquitectura
+
+```
+Windows / WSL2 / Linux host
+  └─ GPU-enabled Docker container
+      └─ Inference runtime
+          ├─ VRAM: hot weights, active layers, activations, KV working set
+          ├─ pinned RAM: CPU-offloaded weights, MoE experts, KV spill/reuse
+          └─ NVMe: mmap shards, disk offload, cold experts, cold KV
+```
+
+## Límite del producto
+
+```
+Docker         = packaging + GPU exposure
+CUDA/runtime   = compute backend
+Planner        = memory law
+Inference engine = execution
+```
+
+## Características principales
+
+1. **Perfilador de hardware:** Detecta la VRAM, la RAM, el tipo de GPU, WSL/Linux nativo, la velocidad de NVMe y la disponibilidad de CUDA.
+2. **Perfilador de modelo:** Detecta si es denso o MoE, la capa más grande, el número total de parámetros, la cuantificación y el crecimiento de KV según la longitud del contexto.
+3. **Planificador de entorno de ejecución:** Genera planes de inicio para llama.cpp, vLLM, Accelerate, TensorRT-LLM o la descarga al estilo DeepSpeed.
+4. **Informe de ubicación:** Muestra qué hay en la VRAM, qué hay en la RAM, qué hay en el disco, el cuello de botella esperado y los tokens/segundo medidos.
+5. **Ruta especializada para MoE:** Mantiene las capas siempre activas en la GPU, dirige los expertos a la CPU/RAM y a la NVMe para la recuperación en caso de inactividad.
+6. **Reducción de riesgos en el enrutamiento:** Mide si el enrutamiento MoE de un modelo está lo suficientemente sesgado como para que una caché por experto sea útil, antes de construirlo (`gpu-container-concentration`).
+7. **Vigilante de seguridad del sistema:** Supervisa la potencia/temperatura/VRAM de la GPU y la memoria del host en comparación con los umbrales configurables; un agente de IA o un bucle autónomo aborta una ejecución antes de que ponga en peligro la máquina (`gpu-container-watchdog`).
+
+## Restricción clave
+
+En Windows/WSL, la sobreasignación de memoria unificada de CUDA **no es la solución**. CUDA trata Windows/WSL como un soporte limitado para la memoria unificada: no hay migración de páginas de GPU de grano fino, ni sobreasignación de memoria de GPU más allá de la VRAM física. Este producto es la **ubicación explícita de la memoria de inferencia**, no el "desbordamiento de VRAM de Docker".
+
+## Estado
+
+Construido y funcionando hoy: `gpu-container-profile`, `gpu-container-plan`, `gpu-container-receipt` (con el bucle de recalibración), `gpu-container-concentration` (reducción de riesgos en el enrutamiento) y `gpu-container-watchdog` (supervisión segura de un trabajo de GPU). llama.cpp es el backend integrado; las matemáticas de ubicación son independientes del backend. Comience con el [inicio rápido](docs/quickstart.md).
+
+## Privacidad y seguridad
+
+`gpu-container` es una **herramienta local y sin conexión**: no realiza llamadas de red y no recopila **ninguna telemetría**, ni por defecto ni de otra manera. Lee las métricas de la GPU (`nvidia-smi` / NVML) y la memoria del host (`psutil`), el archivo `config.json` del modelo que proporciona y los archivos JSON a los que lo apunta; solo escribe en las rutas de salida que especifica. **No** lee ni transmite los parámetros del modelo, las credenciales ni los tokens. Las acciones a nivel de host (`wsl --shutdown`, `docker stop`, `kill`) solo se ejecutan cuando usted acepta explícitamente a través del parámetro `--on-breach` del vigilante; los valores predeterminados nunca tocan su máquina más allá del trabajo que supervisan. Política completa: [SECURITY.md](SECURITY.md).
+
+## Documentación
+
+- [`docs/quickstart.md`](docs/quickstart.md): recorrido completo: perfil → plan → inicio bajo el vigilante → informe → recalibración
+- [`docs/cli.md`](docs/cli.md): los cinco comandos: resumen, opciones, códigos de salida, ejemplos prácticos
+- [`docs/architecture.md`](docs/architecture.md): modelo de niveles de memoria, flujo de datos, enrutamiento de expertos MoE, el bucle de recalibración
+- [`docs/features.md`](docs/features.md): las siete características principales en detalle
+- [`docs/moe-lane-architecture.md`](docs/moe-lane-architecture.md): la ruta MoE insignia en detalle
+- [`docs/derisk-concentration.md`](docs/derisk-concentration.md): la puerta de reducción de riesgos de la caché por experto (concentración del enrutamiento)
+- [`docs/decisions/0001-per-expert-cache-build-vs-upstream.md`](docs/decisions/0001-per-expert-cache-build-vs-upstream.md): ADR-0001: consumir el mecanismo de caché, contribuir a la política
+- [`docs/constraints.md`](docs/constraints.md): objetivos no cumplidos + la corrección de la memoria unificada de CUDA en Windows/WSL
+- [`docs/prior-art.md`](docs/prior-art.md): entornos de ejecución que orquestamos y la brecha que llena este producto
+- [`docs/feasibility.md`](docs/feasibility.md): evaluación de viabilidad, base de investigación y lo que se ha confirmado que funciona
+
+---
+
+<div align="center">
+
+Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> · Licencia MIT
+
+</div>