spark-pulse 1.0.0__tar.gz

spark_pulse-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright © 2026 Kharkevich Engineering Lab
+
+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.
+
+───
+
+Disclaimer: This project is not sponsored by, endorsed by, or affiliated with
+NVIDIA Corporation or any of their subsidiaries. NVIDIA, DGX, and the NVIDIA
+logo are trademarks of NVIDIA Corporation. This product is independent and not
+officially associated with NVIDIA in any way.

spark_pulse-1.0.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: spark-pulse
+Version: 1.0.0
+Summary: Web UI for spark-vllm-docker — recipe management, deployment, and monitoring for DGX Spark
+Maintainer-email: Alexander Kharkevich <alex@kharkevich.org>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/kharkevich-engineering-lab/spark-pulse
+Project-URL: repository, https://github.com/kharkevich-engineering-lab/spark-pulse
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Requires-Dist: sse-starlette>=2.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: click>=8.0
+Requires-Dist: authlib>=1.3.0
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: black>=24.8.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.28; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Dynamic: license-file
+
+# Spark Pulse
+
+Web UI for [spark-vllm-docker](https://github.com/eugr/spark-vllm-docker) — recipe management, deployment, and monitoring for NVIDIA DGX Spark hardware.
+
+**License:** [MIT](LICENSE) — Copyright © 2026 Kharkevich Engineering Lab
+
+> **Disclaimer:** This project is not sponsored by, endorsed by, or affiliated
+> with NVIDIA Corporation or any of its subsidiaries. NVIDIA, DGX, and NVIDIA
+> trademarks are property of their respective owners.
+
+## Features
+
+- **Recipe Browser** — Browse available vLLM deployment recipes, view model details, configs, and mods
+- **Job Management** — Launch deployments with custom parameters, monitor status, view live logs via SSE, stop jobs
+- **Memory Monitor** — Real-time GPU memory, CPU RAM, and disk usage via SSE streaming
+- **Cache Manager** — Browse and clean HF model cache, wheels, ccache, Triton cache, and more
+- **Settings** — Configure spark-vllm-docker path, default container, GPU memory utilization
+- **OIDC Authentication** — Configurable authentication (Keycloak, Auth0, Google, Azure AD, etc.)
+- **Dark/Light Theme** — Switch between dark, light, or system theme (persisted in localStorage)
+- **Custom Modals** — Beautiful confirmation dialogs and error alerts
+- **MCP Server** — Expose spark-vllm-docker operations as Model Context Protocol tools for AI assistants
+
+## Architecture
+
+```
+┌─────────────┐     HTTP / SSE     ┌──────────────────────┐
+│   Browser    │ ◄───────────────► │  FastAPI + Uvicorn   │
+│  React SPA   │                    │  Port 8100           │
+└─────────────┘                    │                      │
+                                   │  spark-vllm-docker/  │
+                                   │  Docker, nvidia-smi  │
+                                   └──────────────────────┘
+```
+
+## Project Structure
+
+```
+spark-pulse/
+├── pyproject.toml           # Python package config (setuptools)
+├── README.md
+├── LICENSE
+│
+├── spark_pulse/             # Python package
+│   ├── __init__.py          # Package init + version
+│   ├── app.py               # FastAPI app factory (creates app, mounts SPA)
+│   ├── cli.py               # CLI: spark-pulse start|install|mcp|...
+│   ├── config.py            # Config loader (YAML + env vars)
+│   ├── service.py           # Systemd service management
+│   ├── auth.py              # OIDC authentication middleware + routes
+│   ├── mcp_server.py        # MCP (Model Context Protocol) server
+│   ├── config.yaml          # Default configuration
+│   ├── routers/             # API route modules
+│   │   ├── recipes.py           # Recipe listing + detail
+│   │   ├── deployments.py       # Deployment CRUD + launch/stop
+│   │   ├── memory.py            # GPU/CPU/disk stats
+│   │   ├── cache.py             # Cache scanning + cleanup
+│   │   └── settings.py          # Settings CRUD
+│   ├── tools/               # Tool abstractions (real/mock swap)
+│   │   ├── __init__.py          # Factory: real vs mock
+│   │   ├── system.py            # nvidia-smi, free, df
+│   │   ├── cache.py             # cache dir scanning
+│   │   └── recipes.py           # YAML recipe parsing
+│   ├── mock/                # Simulation mode implementations
+│   │   ├── system.py              # DGX Spark 128GB mock
+│   │   ├── cache.py               # Plausible cache sizes
+│   │   ├── recipes.py             # 6 realistic recipes
+│   │   └── deployments.py         # In-memory tracker
+│   ├── ui/                  # Built frontend (generated by `npm run build`)
+│   │   └── index.html       # Vite build output
+│   └── data/                # Persistent state (deployments.json)
+│
+├── web/                     # Frontend (separate npm project)
+│   ├── package.json         # Vite + React + TypeScript + Tailwind
+│   ├── vite.config.ts       # Builds to ../spark_pulse/ui/
+│   ├── tsconfig.json
+│   └── src/
+│       ├── main.tsx             # Entry point
+│       ├── App.tsx              # Router + AuthProvider
+│       ├── lib/
+│       │   ├── types.ts         # TypeScript types
+│       │   ├── api.ts           # API client + SSE hooks
+│       │   ├── utils.ts         # Formatting helpers
+│       │   ├── theme.ts         # Theme state manager
+│       │   └── auth.ts          # Auth context
+│       ├── hooks/
+│       │   └── useQuery.ts      # Data fetching hook
+│       ├── components/
+│       │   ├── Layout.tsx       # Sidebar nav + theme toggle
+│       │   ├── StatusBadge.tsx  # Status indicators
+│       │   └── Modal.tsx        # Confirm + Alert modals
+│       └── pages/
+│           ├── RecipesPage.tsx
+│           ├── JobsPage.tsx
+│           ├── MemoryPage.tsx
+│           ├── CachePage.tsx
+│           └── SettingsPage.tsx
+│
+└── scripts/
+    ├── run-dev-server.sh      # Full dev (venv + frontend + backend)
+    ├── run-backend.sh         # Backend only (simulation)
+    ├── run-production.sh      # Production mode
+    └── build-ui.sh            # Build frontend only
+```
+
+## Installation
+
+### As a Python package
+
+```bash
+# Install from local repo
+pip install -e .
+
+# Or with MCP support
+pip install -e ".[mcp]"
+```
+
+This provides the `spark-pulse` CLI command.
+
+### First-time setup
+
+```bash
+# Install Python dependencies (from repo root)
+pip install -e ".[dev]"
+
+# Build frontend
+cd web && npm install && npm run build && cd ..
+
+# Configure (edit spark_pulse/config.yaml or use Settings page)
+# Default spark_vllm_path: /tmp/spark-vllm-docker
+```
+
+## Usage
+
+### Quick start (development)
+
+```bash
+# One command — venv + frontend deps + backend (sim) + frontend dev server
+./scripts/run-dev-server.sh
+# → Frontend: http://localhost:3000
+# → Backend:  http://localhost:8100 (+ /docs Swagger UI)
+```
+
+### Simulation mode (local dev without DGX)
+
+Set `SIMULATION_MODE=1` to get mock data for all APIs — useful for frontend
+development on macOS or any machine without a DGX Spark:
+
+```bash
+# Full dev (includes frontend dev server)
+./scripts/run-dev-server.sh
+
+# Backend only (simulation)
+./scripts/run-backend.sh
+# → http://localhost:8100
+
+# Production mode (real tools, needs spark-vllm-docker + nvidia-smi)
+./scripts/run-production.sh
+
+# Just build frontend into spark_pulse/ui/
+./scripts/build-ui.sh
+```
+
+### Systemd service (production)
+
+```bash
+# Install systemd unit
+sudo spark-pulse install
+
+# Uninstall
+sudo spark-pulse uninstall
+
+# Check status
+spark-pulse status
+
+# Stop service
+spark-pulse stop-service
+```
+
+### MCP Server (AI Assistants)
+
+Expose spark-vllm-docker operations as MCP tools:
+
+```bash
+# Start MCP server (stdio mode for AI assistants)
+spark-pulse mcp
+```
+
+Exposed tools:
+- `list_recipes` — list available deployment recipes
+- `get_recipe` — get recipe details by name
+- `create_deployment` — launch a recipe deployment
+- `stop_deployment` — stop a running deployment
+- `list_deployments` — list all deployments with status
+- `get_memory` — get GPU/CPU/disk stats
+- `list_cache` — list cache directories with sizes
+- `clean_cache` — clean specified cache directories
+- `get_logs` — get deployment logs
+
+### OIDC Authentication
+
+Configure authentication in `spark_pulse/config.yaml`:
+
+```yaml
+auth_enabled: true
+oidc_provider_url: https://keycloak.example.com/realms/myrealm
+oidc_client_id: spark-manager
+oidc_client_secret: your-secret-here
+```
+
+Or via environment variables:
+```bash
+export SPARK_PULSE_AUTH_ENABLED=true
+```
+
+When enabled:
+- All routes are protected except `/health`, `/auth/*`
+- Users are redirected to the OIDC provider on `/auth/login`
+- After successful auth, users see their name and a logout button in the header
+
+### Environment variables
+
+Override config via environment:
+
+```bash
+export SPARK_VLLM_PATH=/path/to/spark-vllm-docker
+export WEBUI_PORT=8100
+export SPARK_PULSE_AUTH_ENABLED=true
+```
+
+## API Reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/recipes` | List all recipes |
+| `GET` | `/api/recipes/{id}` | Recipe details |
+| `GET` | `/api/deployments` | List deployments |
+| `POST` | `/api/deployments` | Create + launch |
+| `DELETE` | `/api/deployments/{id}` | Stop deployment |
+| `GET` | `/api/deployments/{id}/logs` | Recent logs |
+| `GET` | `/api/memory` | All memory stats |
+| `GET` | `/api/memory/gpu` | GPU stats |
+| `GET` | `/api/cache` | Cache dirs + sizes |
+| `POST` | `/api/cache/clean` | Clean caches |
+| `GET` | `/api/settings` | Current settings |
+| `PUT` | `/api/settings` | Update settings |
+| `GET` | `/auth/login` | Redirect to OIDC login |
+| `GET` | `/auth/callback` | OIDC callback |
+| `GET` | `/auth/me` | Current user info |
+| `GET` | `/` | SPA entry point |
+
+## Building for distribution
+
+```bash
+# Build frontend
+cd web && npm run build && cd ..
+
+# Build Python package
+python -m build
+```
+
+The built frontend is bundled into the wheel via `package-data: ui/**/*`.

spark_pulse-1.0.0/README.md

@@ -0,0 +1,261 @@
+# Spark Pulse
+
+Web UI for [spark-vllm-docker](https://github.com/eugr/spark-vllm-docker) — recipe management, deployment, and monitoring for NVIDIA DGX Spark hardware.
+
+**License:** [MIT](LICENSE) — Copyright © 2026 Kharkevich Engineering Lab
+
+> **Disclaimer:** This project is not sponsored by, endorsed by, or affiliated
+> with NVIDIA Corporation or any of its subsidiaries. NVIDIA, DGX, and NVIDIA
+> trademarks are property of their respective owners.
+
+## Features
+
+- **Recipe Browser** — Browse available vLLM deployment recipes, view model details, configs, and mods
+- **Job Management** — Launch deployments with custom parameters, monitor status, view live logs via SSE, stop jobs
+- **Memory Monitor** — Real-time GPU memory, CPU RAM, and disk usage via SSE streaming
+- **Cache Manager** — Browse and clean HF model cache, wheels, ccache, Triton cache, and more
+- **Settings** — Configure spark-vllm-docker path, default container, GPU memory utilization
+- **OIDC Authentication** — Configurable authentication (Keycloak, Auth0, Google, Azure AD, etc.)
+- **Dark/Light Theme** — Switch between dark, light, or system theme (persisted in localStorage)
+- **Custom Modals** — Beautiful confirmation dialogs and error alerts
+- **MCP Server** — Expose spark-vllm-docker operations as Model Context Protocol tools for AI assistants
+
+## Architecture
+
+```
+┌─────────────┐     HTTP / SSE     ┌──────────────────────┐
+│   Browser    │ ◄───────────────► │  FastAPI + Uvicorn   │
+│  React SPA   │                    │  Port 8100           │
+└─────────────┘                    │                      │
+                                   │  spark-vllm-docker/  │
+                                   │  Docker, nvidia-smi  │
+                                   └──────────────────────┘
+```
+
+## Project Structure
+
+```
+spark-pulse/
+├── pyproject.toml           # Python package config (setuptools)
+├── README.md
+├── LICENSE
+│
+├── spark_pulse/             # Python package
+│   ├── __init__.py          # Package init + version
+│   ├── app.py               # FastAPI app factory (creates app, mounts SPA)
+│   ├── cli.py               # CLI: spark-pulse start|install|mcp|...
+│   ├── config.py            # Config loader (YAML + env vars)
+│   ├── service.py           # Systemd service management
+│   ├── auth.py              # OIDC authentication middleware + routes
+│   ├── mcp_server.py        # MCP (Model Context Protocol) server
+│   ├── config.yaml          # Default configuration
+│   ├── routers/             # API route modules
+│   │   ├── recipes.py           # Recipe listing + detail
+│   │   ├── deployments.py       # Deployment CRUD + launch/stop
+│   │   ├── memory.py            # GPU/CPU/disk stats
+│   │   ├── cache.py             # Cache scanning + cleanup
+│   │   └── settings.py          # Settings CRUD
+│   ├── tools/               # Tool abstractions (real/mock swap)
+│   │   ├── __init__.py          # Factory: real vs mock
+│   │   ├── system.py            # nvidia-smi, free, df
+│   │   ├── cache.py             # cache dir scanning
+│   │   └── recipes.py           # YAML recipe parsing
+│   ├── mock/                # Simulation mode implementations
+│   │   ├── system.py              # DGX Spark 128GB mock
+│   │   ├── cache.py               # Plausible cache sizes
+│   │   ├── recipes.py             # 6 realistic recipes
+│   │   └── deployments.py         # In-memory tracker
+│   ├── ui/                  # Built frontend (generated by `npm run build`)
+│   │   └── index.html       # Vite build output
+│   └── data/                # Persistent state (deployments.json)
+│
+├── web/                     # Frontend (separate npm project)
+│   ├── package.json         # Vite + React + TypeScript + Tailwind
+│   ├── vite.config.ts       # Builds to ../spark_pulse/ui/
+│   ├── tsconfig.json
+│   └── src/
+│       ├── main.tsx             # Entry point
+│       ├── App.tsx              # Router + AuthProvider
+│       ├── lib/
+│       │   ├── types.ts         # TypeScript types
+│       │   ├── api.ts           # API client + SSE hooks
+│       │   ├── utils.ts         # Formatting helpers
+│       │   ├── theme.ts         # Theme state manager
+│       │   └── auth.ts          # Auth context
+│       ├── hooks/
+│       │   └── useQuery.ts      # Data fetching hook
+│       ├── components/
+│       │   ├── Layout.tsx       # Sidebar nav + theme toggle
+│       │   ├── StatusBadge.tsx  # Status indicators
+│       │   └── Modal.tsx        # Confirm + Alert modals
+│       └── pages/
+│           ├── RecipesPage.tsx
+│           ├── JobsPage.tsx
+│           ├── MemoryPage.tsx
+│           ├── CachePage.tsx
+│           └── SettingsPage.tsx
+│
+└── scripts/
+    ├── run-dev-server.sh      # Full dev (venv + frontend + backend)
+    ├── run-backend.sh         # Backend only (simulation)
+    ├── run-production.sh      # Production mode
+    └── build-ui.sh            # Build frontend only
+```
+
+## Installation
+
+### As a Python package
+
+```bash
+# Install from local repo
+pip install -e .
+
+# Or with MCP support
+pip install -e ".[mcp]"
+```
+
+This provides the `spark-pulse` CLI command.
+
+### First-time setup
+
+```bash
+# Install Python dependencies (from repo root)
+pip install -e ".[dev]"
+
+# Build frontend
+cd web && npm install && npm run build && cd ..
+
+# Configure (edit spark_pulse/config.yaml or use Settings page)
+# Default spark_vllm_path: /tmp/spark-vllm-docker
+```
+
+## Usage
+
+### Quick start (development)
+
+```bash
+# One command — venv + frontend deps + backend (sim) + frontend dev server
+./scripts/run-dev-server.sh
+# → Frontend: http://localhost:3000
+# → Backend:  http://localhost:8100 (+ /docs Swagger UI)
+```
+
+### Simulation mode (local dev without DGX)
+
+Set `SIMULATION_MODE=1` to get mock data for all APIs — useful for frontend
+development on macOS or any machine without a DGX Spark:
+
+```bash
+# Full dev (includes frontend dev server)
+./scripts/run-dev-server.sh
+
+# Backend only (simulation)
+./scripts/run-backend.sh
+# → http://localhost:8100
+
+# Production mode (real tools, needs spark-vllm-docker + nvidia-smi)
+./scripts/run-production.sh
+
+# Just build frontend into spark_pulse/ui/
+./scripts/build-ui.sh
+```
+
+### Systemd service (production)
+
+```bash
+# Install systemd unit
+sudo spark-pulse install
+
+# Uninstall
+sudo spark-pulse uninstall
+
+# Check status
+spark-pulse status
+
+# Stop service
+spark-pulse stop-service
+```
+
+### MCP Server (AI Assistants)
+
+Expose spark-vllm-docker operations as MCP tools:
+
+```bash
+# Start MCP server (stdio mode for AI assistants)
+spark-pulse mcp
+```
+
+Exposed tools:
+- `list_recipes` — list available deployment recipes
+- `get_recipe` — get recipe details by name
+- `create_deployment` — launch a recipe deployment
+- `stop_deployment` — stop a running deployment
+- `list_deployments` — list all deployments with status
+- `get_memory` — get GPU/CPU/disk stats
+- `list_cache` — list cache directories with sizes
+- `clean_cache` — clean specified cache directories
+- `get_logs` — get deployment logs
+
+### OIDC Authentication
+
+Configure authentication in `spark_pulse/config.yaml`:
+
+```yaml
+auth_enabled: true
+oidc_provider_url: https://keycloak.example.com/realms/myrealm
+oidc_client_id: spark-manager
+oidc_client_secret: your-secret-here
+```
+
+Or via environment variables:
+```bash
+export SPARK_PULSE_AUTH_ENABLED=true
+```
+
+When enabled:
+- All routes are protected except `/health`, `/auth/*`
+- Users are redirected to the OIDC provider on `/auth/login`
+- After successful auth, users see their name and a logout button in the header
+
+### Environment variables
+
+Override config via environment:
+
+```bash
+export SPARK_VLLM_PATH=/path/to/spark-vllm-docker
+export WEBUI_PORT=8100
+export SPARK_PULSE_AUTH_ENABLED=true
+```
+
+## API Reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/recipes` | List all recipes |
+| `GET` | `/api/recipes/{id}` | Recipe details |
+| `GET` | `/api/deployments` | List deployments |
+| `POST` | `/api/deployments` | Create + launch |
+| `DELETE` | `/api/deployments/{id}` | Stop deployment |
+| `GET` | `/api/deployments/{id}/logs` | Recent logs |
+| `GET` | `/api/memory` | All memory stats |
+| `GET` | `/api/memory/gpu` | GPU stats |
+| `GET` | `/api/cache` | Cache dirs + sizes |
+| `POST` | `/api/cache/clean` | Clean caches |
+| `GET` | `/api/settings` | Current settings |
+| `PUT` | `/api/settings` | Update settings |
+| `GET` | `/auth/login` | Redirect to OIDC login |
+| `GET` | `/auth/callback` | OIDC callback |
+| `GET` | `/auth/me` | Current user info |
+| `GET` | `/` | SPA entry point |
+
+## Building for distribution
+
+```bash
+# Build frontend
+cd web && npm run build && cd ..
+
+# Build Python package
+python -m build
+```
+
+The built frontend is bundled into the wheel via `package-data: ui/**/*`.

spark_pulse-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+# ── Project metadata ────────────────────────────────────────────────────────
+
+[project]
+name = "spark-pulse"
+version = "1.0.0"
+description = "Web UI for spark-vllm-docker — recipe management, deployment, and monitoring for DGX Spark"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "sse-starlette>=2.2.0",
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+    "click>=8.0",
+    "authlib>=1.3.0",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black>=24.8.0",
+    "pytest>=8.0",
+    "httpx>=0.28",
+]
+mcp = [
+    "mcp>=1.0.0",
+]
+
+[[project.maintainers]]
+name = "Alexander Kharkevich"
+email = "alex@kharkevich.org"
+
+[project.urls]
+homepage = "https://github.com/kharkevich-engineering-lab/spark-pulse"
+repository = "https://github.com/kharkevich-engineering-lab/spark-pulse"
+
+# ── Console script ──────────────────────────────────────────────────────────
+
+[project.scripts]
+spark-pulse = "spark_pulse.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "--tb=short -v"
+
+# ── Packaging ───────────────────────────────────────────────────────────────
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spark_pulse*", "spark_pulse.*"]
+
+[tool.setuptools.package-data]
+spark_pulse = [
+    "ui/**/*",
+    "service/templates/**/*",
+]

spark_pulse-1.0.0/setup.cfg

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

spark_pulse-1.0.0/spark_pulse/__init__.py

@@ -0,0 +1,3 @@
+"""Spark Manager — Web UI for spark-vllm-docker."""
+
+__version__ = "0.1.0"