ProcPlan initial release

Author: ulvgard

Dockerfile

@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1
+FROM python:3.13-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /app
+COPY . /app
+
+RUN python -m pip install --upgrade pip
+
+EXPOSE 8080
+
+ENTRYPOINT ["python", "-m", "procplan.server"]
+CMD ["--config", "/data/config.json", "--database", "/data/procplan.db", "--host", "0.0.0.0", "--port", "8080"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ProcPlan Maintainers
+
+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.

README.md

@@ -0,0 +1,136 @@
+# ProcPlan – GPU Resource Planner
+
+<img src="screenshot.png" alt="ProcPlan calendar view" width="720" />
+
+ProcPlan is a dependency-free GPU resource planner built entirely on the Python
+standard library and SQLite. It ships with:
+
+- **Visual daily planner** – drag across the GPU × day grid to reserve time with
+  priority badges and conflict checks.
+- **Command-line snapshots** – `procplan-cli` summarizes availability by GPU and day.
+- **Early finish notifier** – `procplan-notify` (or a single Python import)
+  releases slots the moment experiments complete.
+- **Container + scripts** – run locally or via Docker/Podman with one command.
+
+---
+
+## Quick Start
+
+```bash
+pip install git+https://github.com/ulvgard/procplan.git
+# or install from a local clone: pip install .
+# Both expose procplan-cli, procplan-server, procplan-notify
+python -m procplan.server \
+  --config config.json \
+  --database data/procplan.db \
+  --host 0.0.0.0 \
+  --port 8080
+```
+
+Open the web UI at `http://localhost:8080/`, select **All nodes**, and drag over
+free cells to create bookings.
+
+Prefer containers?
+```bash
+docker compose up --build
+```
+Volumes map `config.sample.json` into the container and persist state under
+`./data`.
+
+---
+
+## CLI in 30 Seconds
+
+```bash
+procplan-cli --url http://localhost:8080 --all      # weekly view for every node
+procplan-cli --url http://localhost:8080            # defaults to your host name
+procplan-cli --url http://localhost:8080 --node node-a --date 2024-06-01
+```
+
+Example output:
+
+```
+Node Training Node A (node-a)
+Window: 2024-06-01T00:00:00+00:00 – 2024-06-08T00:00:00+00:00
+GPU              | 2024-06-01 | 2024-06-02 | 2024-06-03 | 2024-06-04 | 2024-06-05 | 2024-06-06 | 2024-06-07
+------------------------------------------------------------------------------------------------------------
+node-a-gpu0 (A100) | AB (High)  | -          | -          | CD (Medium)| -          | -          | -
+node-a-gpu1 (A100) | -          | -          | EF (Low)   | -          | -          | -          | -
+node-a-gpu2 (A100) | -          | -          | -          | -          | AB (High)  | -          | -
+node-a-gpu3 (A100) | -          | -          | -          | -          | -          | -          | -
+```
+Columns are days, rows are GPUs, and each cell shows the booking initials with
+priority.
+
+---
+
+## Notify and Release Early
+
+### Python helper
+```python
+from procplan.notifier import signal_completion
+
+result = signal_completion("http://scheduler.internal:8080", booking_id=42)
+if not result.ok:
+    print(f"Unable to notify scheduler ({result.status}): {result.message}")
+```
+
+### CLI helper
+```bash
+procplan-notify --url http://scheduler.internal:8080 --booking-id 42
+```
+
+---
+
+## HTTP API Highlights
+
+| Method | Path               | Description                                         |
+|--------|--------------------|-----------------------------------------------------|
+| GET    | `/api/nodes`       | List configured nodes and their GPUs.               |
+| GET    | `/api/availability` | Per-hour availability (ISO 8601 timestamps).        |
+| POST   | `/api/book`        | Create a booking (specify `gpu_ids` or `gpu_count`). |
+| POST   | `/api/mark_done`   | Mark an active booking complete.                    |
+| POST   | `/api/reload_config` | Reload node topology from disk.                    |
+
+All timestamps are UTC and snap to whole hours.
+
+---
+
+## Getting Started (Deep Dive)
+
+1. **Describe your cluster** in JSON. `config.sample.json` is a template:
+   ```json
+   {
+     "nodes": [
+       {
+         "id": "node-a",
+         "name": "Training Node A",
+         "gpus": [
+           {"id": "node-a-gpu0", "kind": "A100"},
+           {"id": "node-a-gpu1", "kind": "A100"}
+         ]
+       }
+     ]
+   }
+   ```
+
+2. **Serve ProcPlan** with the command from *Quick Start* or via `docker compose`.
+   The server creates the SQLite database automatically. Call `POST /api/reload_config`
+   to pick up topology changes without downtime.
+
+3. **Book GPUs** through the web UI or CLI. Bookings require initials, duration,
+   and either specific GPU IDs or a count. Drag-selecting in the UI fills these
+   automatically.
+
+---
+
+## Development Notes
+
+- Requires **Python 3.11+** (built and tested on Python 3.13).
+- Uses **only the Python standard library**; no third-party dependencies.
+- SQLite operates in WAL mode for concurrency; the database file lives wherever
+  you point `--database`.
+- Static assets ship inside `procplan/web`; override with `--web-root` if needed.
+
+ProcPlan v1.0.0 is ready for teams who want reliable GPU scheduling without a
+stack of services. Happy planning!

bin/run-container.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+cd "$REPO_DIR"
+
+if ! command -v docker >/dev/null 2>&1; then
+  echo "docker is required to run the container" >&2
+  exit 1
+fi
+
+docker compose up --build "$@"

bin/run-server.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+CONFIG_FILE=${1:-config.sample.json}
+DB_PATH=${2:-data/procplan.db}
+
+cd "$REPO_DIR"
+mkdir -p "$(dirname "$DB_PATH")"
+
+python -m procplan.server \
+  --config "$CONFIG_FILE" \
+  --database "$DB_PATH" \
+  --host 0.0.0.0 \
+  --port 8080

config.sample.json

@@ -0,0 +1,23 @@
+{
+  "nodes": [
+    {
+      "id": "node-a",
+      "name": "Node A",
+      "gpus": [
+        {"id": "node-a-gpu0", "kind": "A100"},
+        {"id": "node-a-gpu1", "kind": "A100"},
+        {"id": "node-a-gpu2", "kind": "A100"},
+        {"id": "node-a-gpu3", "kind": "A100"}
+      ]
+    },
+    {
+      "id": "node-b",
+      "name": "Node B",
+      "gpus": [
+        {"id": "node-b-gpu0", "kind": "RTX6000"},
+        {"id": "node-b-gpu1", "kind": "RTX6000"}
+      ]
+    }
+  ]
+}
+

data/.gitkeep

@@ -0,0 +1,13 @@
+services:
+  procplan:
+    build: .
+    image: procplan:latest
+    container_name: procplan
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./config.sample.json:/data/config.json:ro
+      - ./data:/data
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PYTHONDONTWRITEBYTECODE=1

docker-compose.yml

@@ -0,0 +1,5 @@
+"""Compute node resource planning toolkit."""
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"