pynode-flow 0.2.8__tar.gz → 0.2.9__tar.gz

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/.claude/skills/pynode-workflows/SKILL.md

@@ -90,12 +90,13 @@ Other vision nodes: `DrawPredictionsNode`, `CropNode`,
 read their `DEFAULT_CONFIG`/`properties` in `pynode/nodes/<Name>/` before use.
 
 ### Supervision
-Nodes built on the `supervision` library (`[vision]` extra). They register even
-without it installed, reporting an error and passing messages through.
+Nodes built on the `supervision` library plus Roboflow's `trackers` (both in the
+`[vision]` extra) and `reid` (`[reid]` extra). They register even without them installed, reporting an error and passing messages through.
 
 | Type | Ports | Config |
 |---|---|---|
-| `SupervisionTrackerNode` | 1→1 | `track_thresh`: "0.25"; `track_buffer`: "30" (frames a lost track is kept, scaled by `frame_rate`); `match_thresh`: "0.8" (IoU); `min_consecutive_frames`: "1" (raise to 2-3 to kill ghost tracks); `frame_rate`: "30" (**set to the real source fps**). Adds `track_id` to each detection plus `payload.tracks`/`track_count`. Has a `reset` action — a new object needs 2 frames before it is reported. **Does not draw** — wire an `SupervisionAnnotateNode` after it. |
+| `SupervisionTrackerNode` | 1→1 | `algorithm`: `bytetrack` (default)\|`sort`\|`ocsort`\|`botsort` (from Roboflow's `trackers` package — `sv.ByteTrack` was removed in supervision 0.31); `track_thresh`: "0.25" (confidence to start a track); `high_thresh`: "" (blank = same as `track_thresh`); `track_buffer`: "30" (frames a lost track is kept, scaled by `frame_rate`); `min_iou`: "0.2" (**a real IoU** — the legacy `match_thresh` was an IoU *distance* and is auto-translated as `1 - value`; do not write `match_thresh` in new flows); `min_consecutive_frames`: "1" (raise to 2-3 to kill ghost tracks); `frame_rate`: "30" (**set to the real source fps**); `keep_untracked`: false (true = also pass detections with no track yet, without a `track_id`); `camera_motion`: false (ocsort/botsort, needs `payload.image`); botsort only: `reid_model`: `none`\|a Re-ID alias (needs `[reid]` extra + `payload.image`), `reid_device`: `auto`\|`cpu`\|`cuda`, `reid_appearance_thresh`: "0.25". Adds `track_id` (**0-based**) to each detection plus `payload.tracks`/`track_count`. Has a `reset` action — a new object needs 2 frames before it is reported. Thresholds apply live; changing algorithm/buffer/frame rate/camera motion/Re-ID rebuilds the tracker (ids restart). **Does not draw** — wire an `SupervisionAnnotateNode` after it. |
+| `SupervisionReIDNode` | 1→**2** | Appearance re-identification (`reid` package, `[reid]` extra). `model`: `osnet_x1_0_msmt17_combineall` (default)\|`osnet_x1_0_mot17`\|`osnet_x1_0_sportsmot`\|`osnet_x1_0_dancetrack`\|`osnet_x1_0_soccernet`\|`fastreid_mot17_sbs50`\|`custom` (+ `custom_model`: hf://, https:// or local path); `device`: `auto`\|`cpu`\|`cuda`; `classes`: "person" (comma names/ids, blank = all); `match_distance`: "0.3" (max cosine distance, lower = stricter); `gallery`: "" (blank = private; **same name on several nodes = shared identities / cross-camera**); `use_as_track_id`: false (true = `track_id` becomes the identity so annotate/zone/line nodes follow it; original kept in `sv.data.local_track_id`); `refresh_interval`: "10" (frames between re-embeds of a tracked object); `ttl_seconds`: "0" (0 = never forget); `max_identities`: "1000"; `min_box_size`: "16"; `include_embeddings`: false. **Needs `payload.image`**; place after an SV Tracker (works without one, slower). Output 0 = msg with `reid_id` on each identified detection + `payload.identities`/`identity_count`; **output 1 = events** `{event:'new'\|'reidentified', reid_id, track_id?, bbox, class_name, source, gallery, distance?, absent_seconds?, previous_source?}` (topic `reid/<event>`). Model loads in the background on first frame (frames pass through until ready). `reset` action clears the gallery. SV Annotate labels show `ID<n>` when a `reid_id` is present. |
 | `SupervisionAnnotateNode` | 1→1 | `annotators`: list from `box round_box box_corner ellipse circle triangle dot color label percentage_bar blur pixelate background_overlay trace heatmap` (applied in a fixed order: pixel effects → shapes → labels; default `["box","label"]`); `color_lookup`: `class`\|`track`\|`index` (`track` falls back to `class` without ids); `thickness`/`text_scale`: "auto" (resolution-scaled) or a number; `show_class`/`show_confidence`/`show_track_id`: bool (label content); `trace_length`: "30". `trace` needs a `SupervisionTrackerNode` upstream; `heatmap` accumulates over time. `reset` action clears trace/heatmap state. |
 | `SupervisionLineCounterNode` | 1→**2** | `line`: "x1,y1,x2,y2" (image px; the GUI has a draw-on-frame editor); `anchors`: `corners`\|`center`\|`bottom_center`; `min_crossing_frames`: "1"; `draw`: "true"/"false". **Needs tracked detections** (SV Tracker upstream). Output 0 = every msg + `payload.line_in`/`line_out`/`line_in_by_class`/`line_out_by_class` and the line drawn; **output 1 = one msg per crossing** `{event:'line_crossing', direction, track_id, class_id, class_name, bbox, in_count, out_count}`. Actions: `reset` (zero counts), `set_geometry` (live line update, resets counts). |
 | `SupervisionZoneNode` | 1→**2** | `polygon`: JSON "[[x,y],...]" (image px; draw-on-frame editor in GUI); `anchor`: `bottom_center`\|`center`\|`top_center`; `filter_to_zone`: bool (drop outside detections); `draw`: "true"/"false"; `opacity`: "0.15". Output 0 = every msg + `payload.zone_count` and `in_zone` on each detection; **output 1 = enter/exit events** (needs track ids) `{event:'enter'\|'exit', track_id, class_id, class_name, bbox, zone_count}`. Actions: `reset` (event state), `set_geometry` (live polygon update). |

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/.dockerignore

@@ -20,3 +20,6 @@ build/
 .DS_Store
 logs/
 *.log
+# Credential store and its key: never bake them into an image
+workflows/credentials.json
+**/.credential_key

pynode_flow-0.2.9/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  # Weekly run against the latest releases of every dependency: upstream
+  # removals (e.g. supervision 0.31 dropping sv.ByteTrack) surface here
+  # instead of in a user's install.
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - 3.11
+          - 3.12
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install system libraries for OpenCV
+        run: sudo apt-get update && sudo apt-get install -y libgl1 libglib2.0-0
+
+      - name: Install package
+        run: pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest -q
+
+  # The core job installs no ML packages, so every Supervision / tracker /
+  # Re-ID test is skipped there (pytest.importorskip). This job installs the
+  # CPU builds so those nodes are actually exercised.
+  test-vision:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install system libraries for OpenCV
+        run: sudo apt-get update && sudo apt-get install -y libgl1 libglib2.0-0
+
+      - name: Install CPU torch
+        run: pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install package with vision, reid and mqtt extras
+        run: pip install -e ".[dev,reid,mqtt]"
+
+      - name: Show resolved versions
+        run: pip list | grep -i -E "supervision|trackers|reid|torch|ultralytics|numpy|opencv|paho"
+
+      - name: Run tests (deprecations from our own code are errors)
+        run: pytest -q -W "error::DeprecationWarning:pynode"
+
+  typecheck:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package and pyright
+        run: pip install -e .[dev] pyright
+
+      - name: Run pyright
+        run: pyright

pynode_flow-0.2.9/.github/workflows/git-hooks.yml

@@ -0,0 +1,28 @@
+name: "Git Hooks"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: ~
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  run-prek:
+    name: prek run --all-files
+    runs-on: ubuntu-26.04
+    timeout-minutes: 1
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Run prek
+        uses: j178/prek-action@1382ad72dea72f9d53832f2bcb65b3e87a947204  # v3.0.1

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/.gitignore

@@ -155,6 +155,9 @@ Thumbs.db
 # ...and the example Node-RED flow shipped with the SocketNode nodes
 !pynode/nodes/SocketNode/interop/*.json
 
+# Credential store key, generated next to credentials.json on first use
+.credential_key
+
 # PyTorch model files
 *.pt
 models/

pynode_flow-0.2.9/.pre-commit-config.yml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+        args: [
+          "--fix",
+          "--show-fixes",
+        ]

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/DOCKER.md

@@ -60,8 +60,9 @@ deploy:
 ### Persistent Storage
 
 The following directories are mounted for persistence:
-- `./workflows` - Saved workflows
-- `./logs` - Application logs
+- `./models` - Downloaded model weights (YOLO, Re-ID; Hugging Face downloads land in `models/huggingface` via `HF_HOME`). Without this volume every new container downloads them again.
+- `./logs` - `pynode.log`, rotated at 10 MB with 5 backups (`PYNODE_LOG_FILE`).
+- `./workflows` - Saved workflows, plus the credential store (`credentials.json`) and, unless `PYNODE_CREDENTIAL_KEY` or `PYNODE_CREDENTIAL_KEY_FILE` is set, its generated key (`.credential_key`). Back up both files together. Stop PyNode before restoring `credentials.json` from a backup: a running instance keeps the store in memory and would overwrite the restored file on its next change.
 
 ## Building
 

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/Dockerfile

@@ -76,7 +76,7 @@ EXPOSE 5000
 
 # Health check (uses the bundled Python interpreter; no extra tools required)
 HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
-    CMD ["/app/appenv/bin/python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/')"]
+    CMD ["/app/appenv/bin/python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/healthz')"]
 
 ENTRYPOINT ["/app/docker-entrypoint.sh"]
 CMD ["/app/appenv/bin/python", "-m", "pynode", "--production", "--host", "0.0.0.0", "--port", "5000"]

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/Dockerfile.cpu

@@ -56,7 +56,7 @@ EXPOSE 5000
 
 # Health check (uses the bundled Python interpreter; no extra tools required)
 HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
-    CMD ["/app/appenv/bin/python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/')"]
+    CMD ["/app/appenv/bin/python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/healthz')"]
 
 ENTRYPOINT ["/app/docker-entrypoint.sh"]
 CMD ["/app/appenv/bin/python", "-m", "pynode", "--production", "--host", "0.0.0.0", "--port", "5000"]

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/INSTALL.md

@@ -32,7 +32,8 @@ Install only the node groups you need:
 
 | Extra | Installs | Nodes it enables |
 |-------|----------|------------------|
-| `vision` | ultralytics, torch, torchvision, supervision | UltralyticsNode, DrawPredictionsNode, the Supervision nodes, … |
+| `vision` | ultralytics, torch, torchvision, supervision, trackers | UltralyticsNode, DrawPredictionsNode, the Supervision nodes (tracking, zones, annotators), … |
+| `reid` | reid (+ `vision`) | SV Re-ID node, BoT-SORT appearance association in SV Tracker |
 | `mqtt` | paho-mqtt | MQTTNode |
 | `camera` | framesource[full] | FrameSourceNode |
 | `inference` | onnxruntime (+ `vision`) | InferenceNode |
@@ -102,6 +103,14 @@ pynode --host 0.0.0.0 --port 5000 --production
 - `--host`: Host address to bind to (default: 0.0.0.0)
 - `--port`: Port to bind to (default: 5000)
 - `--production`: Run in production mode using Waitress server
+- `--threads`: Request threads in production mode (default: 32, or `PYNODE_THREADS`)
+- `--api-key`: Require an API key on all `/api/` requests (or `PYNODE_API_KEY`)
+- `--cors-origins`: Comma-separated allowed browser origins (or `PYNODE_CORS_ORIGINS`)
+- `--data-dir` / `--models-dir`: Where workflows and model weights are stored
+- `--log-level`: DEBUG, INFO, WARNING or ERROR (default: INFO)
+- `--log-file`: Also log to a rotating file (or `PYNODE_LOG_FILE`)
+
+See "Running in Production" in the README for health checks, shutdown behaviour and reverse-proxy notes.
 
 ## Installing Node Dependencies
 

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynode-flow
-Version: 0.2.8
+Version: 0.2.9
 Summary: Python based Node-RED-like visual workflow system
 Author: olkham
 License-Expression: MIT
@@ -26,11 +26,16 @@ Requires-Dist: flask-cors>=4.0
 Requires-Dist: waitress>=2.1
 Requires-Dist: numpy
 Requires-Dist: opencv-python
+Requires-Dist: cryptography>=42
 Provides-Extra: vision
 Requires-Dist: ultralytics; extra == "vision"
 Requires-Dist: torch; extra == "vision"
 Requires-Dist: torchvision; extra == "vision"
-Requires-Dist: supervision; extra == "vision"
+Requires-Dist: supervision>=0.31.0; extra == "vision"
+Requires-Dist: trackers>=2.7.0; extra == "vision"
+Provides-Extra: reid
+Requires-Dist: pynode-flow[vision]; extra == "reid"
+Requires-Dist: reid>=0.1.0; extra == "reid"
 Provides-Extra: mqtt
 Requires-Dist: paho-mqtt; extra == "mqtt"
 Provides-Extra: camera
@@ -53,6 +58,7 @@ Requires-Dist: pynode-flow[mqtt]; extra == "full"
 Requires-Dist: pynode-flow[camera]; extra == "full"
 Requires-Dist: pynode-flow[inference]; extra == "full"
 Requires-Dist: pynode-flow[vlm]; extra == "full"
+Requires-Dist: pynode-flow[reid]; extra == "full"
 Requires-Dist: pynode-flow[upload]; extra == "full"
 Requires-Dist: pynode-flow[discovery]; extra == "full"
 Provides-Extra: all
@@ -67,7 +73,10 @@ Dynamic: license-file
 
 A Node-RED-like visual workflow editor with a Python backend. Create workflows by connecting Python nodes that process and route messages.
 
-https://github.com/user-attachments/assets/0b53085a-2cc6-4c26-bd43-e0de1e0716a2
+<!-- https://github.com/user-attachments/assets/0b53085a-2cc6-4c26-bd43-e0de1e0716a2 -->
+[![Watch the PyNode promo video on YouTube](docs/video_thumb_play.png)](https://www.youtube.com/watch?v=d-sQIWd4X9Q)
+
+<p align="center"><a href="https://www.youtube.com/watch?v=d-sQIWd4X9Q">▶ Watch the promo video on YouTube</a></p>
 
 ## Features
 
@@ -95,7 +104,7 @@ carries its own documentation in the editor's **Information** panel (ℹ️ tab)
 | **Logic** | Switch (route on conditions), Gate, Sync, Auto Sync |
 | **Network** | MQTT In / Out, UDP In / Out, TCP In / Out, REST Endpoint, Webhook, mDNS Broadcast / Discovery |
 | **Vision** | YOLO, Inference, Crop, Slice Image / Slice Collector, Draw Predictions, Class Map (relabel classes), Confidence Filter, Label Filter, Merge Predictions, Image Format, Qwen3-VL, vLLM |
-| **Supervision** | SV Tracker (ByteTrack), SV Annotate (15 visual styles: boxes, labels, traces, heat maps, privacy blur/pixelate), SV Line Counter (in/out crossing counts + events), SV Polygon Zone (occupancy, enter/exit events) — zone geometry drawn directly on a live frame — SV Smoother (de-jitter boxes), SV Detection Filter (confidence/class/area/aspect/top-K + NMS/NMM), SV Sink (CSV/JSON detection logging) |
+| **Supervision** | SV Tracker (ByteTrack / SORT / OC-SORT / BoT-SORT via Roboflow `trackers`), SV Re-ID (appearance identities that survive occlusion and carry across cameras), SV Annotate (15 visual styles: boxes, labels, traces, heat maps, privacy blur/pixelate), SV Line Counter (in/out crossing counts + events), SV Polygon Zone (occupancy, enter/exit events) — zone geometry drawn directly on a live frame — SV Smoother (de-jitter boxes), SV Detection Filter (confidence/class/area/aspect/top-K + NMS/NMM), SV Sink (CSV/JSON detection logging) |
 | **Analysis** | BBox Metrics, Polygon Metrics, Point in Shape |
 | **OpenCV** | ~28 image-processing nodes: Blur, Threshold, Morphology, Edge Detector, Find Contours, Perspective, Resize, Rotate, Colormap, Histogram, FFT, Template Match, RealSense Depth, and more |
 | **Node Probes** | Rate Probe, Queue Length Probe, Counter |
@@ -256,8 +265,25 @@ order:
 
 - **API key**: start with `pynode --api-key <secret>` (or set the `PYNODE_API_KEY` env var). All `/api/` requests then require the key via the `X-API-Key` header or an `api_key` query parameter; the web UI prompts for it on first load and remembers it in the browser. Unset/empty = no authentication (the default).
 - **CORS**: restrict allowed browser origins with `pynode --cors-origins http://localhost:5000,https://myhost` (or the `PYNODE_CORS_ORIGINS` env var). Default is `*` (all origins).
+- **Credentials**: nodes that need a secret (Webhook and REST Endpoint authentication, the Roboflow Upload API key, the Qwen3-VL HuggingFace token) and MQTT brokers (the password) reference a stored credential by ID instead of keeping the secret in the workflow or the broker settings. Secrets saved in plain text by earlier versions keep working until you select a credential in their place. Secrets are encrypted in `<data dir>/workflows/credentials.json` and are never sent back to the browser. The encryption key comes from `PYNODE_CREDENTIAL_KEY` (a Fernet key, e.g. from `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`) or from the file named by `PYNODE_CREDENTIAL_KEY_FILE`. With neither set, PyNode generates `<data dir>/workflows/.credential_key` on first use and logs its location. Back up the key together with `credentials.json`, because the secrets cannot be recovered without it. If the data directory may be copied elsewhere, supply the key from outside it. Credentials prevent accidental exposure, not a malicious flow editor: anyone who can edit and deploy flows (e.g. with a Function node) can use any stored credential.
 - **Bind locally**: when you don't need network access, run `pynode --host 127.0.0.1` so the server is only reachable from the local machine.
 
+PyNode logs a warning at startup when it is listening on a network interface without an API key.
+
+## Running in Production
+
+```bash
+pynode --production --host 0.0.0.0 --api-key "$PYNODE_API_KEY" --log-file /var/log/pynode/pynode.log
+```
+
+- **Server**: `--production` serves through Waitress. `--threads N` (or `PYNODE_THREADS`, default 32) sets the request threads. Every open editor tab holds one for its event stream and every live MJPEG viewer holds another, so raise it if many people watch at once.
+- **Health checks**: `GET /healthz` is an unauthenticated liveness probe for Docker, Kubernetes or a load balancer. `GET /api/health` (API key required) returns the version, uptime and the run state of every workflow, for monitoring and alerting.
+- **Graceful shutdown**: on `SIGTERM` (`docker stop`, systemd, Kubernetes) and Ctrl+C, PyNode stops every workflow before exiting, so video writers finalise their files, detection logs are flushed and cameras are released. Give the supervisor a stop timeout of 10 seconds or more.
+- **Logs**: `--log-file <path>` (or `PYNODE_LOG_FILE`) adds a rotating log file (10 MB, 5 backups) next to console output.
+- **Upload limit**: request bodies are capped at 4096 MB; change it with `PYNODE_MAX_UPLOAD_MB` (`0` = unlimited).
+- **TLS**: PyNode speaks plain HTTP. Terminate TLS in a reverse proxy (nginx, Caddy, Traefik) and disable response buffering for `/api/debug/stream` and the MJPEG routes, which are long-lived streams.
+- **Persistent data**: keep the data directory (`--data-dir`, workflows and credentials) and the models directory (`--models-dir`, downloaded weights) on persistent storage. See [DOCKER.md](DOCKER.md) for the container setup.
+
 ## Docker Setup
 
 PyNode can be run in a Docker container with GPU support (CUDA 12.6).

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/README.md

@@ -2,7 +2,10 @@
 
 A Node-RED-like visual workflow editor with a Python backend. Create workflows by connecting Python nodes that process and route messages.
 
-https://github.com/user-attachments/assets/0b53085a-2cc6-4c26-bd43-e0de1e0716a2
+<!-- https://github.com/user-attachments/assets/0b53085a-2cc6-4c26-bd43-e0de1e0716a2 -->
+[![Watch the PyNode promo video on YouTube](docs/video_thumb_play.png)](https://www.youtube.com/watch?v=d-sQIWd4X9Q)
+
+<p align="center"><a href="https://www.youtube.com/watch?v=d-sQIWd4X9Q">▶ Watch the promo video on YouTube</a></p>
 
 ## Features
 
@@ -30,7 +33,7 @@ carries its own documentation in the editor's **Information** panel (ℹ️ tab)
 | **Logic** | Switch (route on conditions), Gate, Sync, Auto Sync |
 | **Network** | MQTT In / Out, UDP In / Out, TCP In / Out, REST Endpoint, Webhook, mDNS Broadcast / Discovery |
 | **Vision** | YOLO, Inference, Crop, Slice Image / Slice Collector, Draw Predictions, Class Map (relabel classes), Confidence Filter, Label Filter, Merge Predictions, Image Format, Qwen3-VL, vLLM |
-| **Supervision** | SV Tracker (ByteTrack), SV Annotate (15 visual styles: boxes, labels, traces, heat maps, privacy blur/pixelate), SV Line Counter (in/out crossing counts + events), SV Polygon Zone (occupancy, enter/exit events) — zone geometry drawn directly on a live frame — SV Smoother (de-jitter boxes), SV Detection Filter (confidence/class/area/aspect/top-K + NMS/NMM), SV Sink (CSV/JSON detection logging) |
+| **Supervision** | SV Tracker (ByteTrack / SORT / OC-SORT / BoT-SORT via Roboflow `trackers`), SV Re-ID (appearance identities that survive occlusion and carry across cameras), SV Annotate (15 visual styles: boxes, labels, traces, heat maps, privacy blur/pixelate), SV Line Counter (in/out crossing counts + events), SV Polygon Zone (occupancy, enter/exit events) — zone geometry drawn directly on a live frame — SV Smoother (de-jitter boxes), SV Detection Filter (confidence/class/area/aspect/top-K + NMS/NMM), SV Sink (CSV/JSON detection logging) |
 | **Analysis** | BBox Metrics, Polygon Metrics, Point in Shape |
 | **OpenCV** | ~28 image-processing nodes: Blur, Threshold, Morphology, Edge Detector, Find Contours, Perspective, Resize, Rotate, Colormap, Histogram, FFT, Template Match, RealSense Depth, and more |
 | **Node Probes** | Rate Probe, Queue Length Probe, Counter |
@@ -191,8 +194,25 @@ order:
 
 - **API key**: start with `pynode --api-key <secret>` (or set the `PYNODE_API_KEY` env var). All `/api/` requests then require the key via the `X-API-Key` header or an `api_key` query parameter; the web UI prompts for it on first load and remembers it in the browser. Unset/empty = no authentication (the default).
 - **CORS**: restrict allowed browser origins with `pynode --cors-origins http://localhost:5000,https://myhost` (or the `PYNODE_CORS_ORIGINS` env var). Default is `*` (all origins).
+- **Credentials**: nodes that need a secret (Webhook and REST Endpoint authentication, the Roboflow Upload API key, the Qwen3-VL HuggingFace token) and MQTT brokers (the password) reference a stored credential by ID instead of keeping the secret in the workflow or the broker settings. Secrets saved in plain text by earlier versions keep working until you select a credential in their place. Secrets are encrypted in `<data dir>/workflows/credentials.json` and are never sent back to the browser. The encryption key comes from `PYNODE_CREDENTIAL_KEY` (a Fernet key, e.g. from `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`) or from the file named by `PYNODE_CREDENTIAL_KEY_FILE`. With neither set, PyNode generates `<data dir>/workflows/.credential_key` on first use and logs its location. Back up the key together with `credentials.json`, because the secrets cannot be recovered without it. If the data directory may be copied elsewhere, supply the key from outside it. Credentials prevent accidental exposure, not a malicious flow editor: anyone who can edit and deploy flows (e.g. with a Function node) can use any stored credential.
 - **Bind locally**: when you don't need network access, run `pynode --host 127.0.0.1` so the server is only reachable from the local machine.
 
+PyNode logs a warning at startup when it is listening on a network interface without an API key.
+
+## Running in Production
+
+```bash
+pynode --production --host 0.0.0.0 --api-key "$PYNODE_API_KEY" --log-file /var/log/pynode/pynode.log
+```
+
+- **Server**: `--production` serves through Waitress. `--threads N` (or `PYNODE_THREADS`, default 32) sets the request threads. Every open editor tab holds one for its event stream and every live MJPEG viewer holds another, so raise it if many people watch at once.
+- **Health checks**: `GET /healthz` is an unauthenticated liveness probe for Docker, Kubernetes or a load balancer. `GET /api/health` (API key required) returns the version, uptime and the run state of every workflow, for monitoring and alerting.
+- **Graceful shutdown**: on `SIGTERM` (`docker stop`, systemd, Kubernetes) and Ctrl+C, PyNode stops every workflow before exiting, so video writers finalise their files, detection logs are flushed and cameras are released. Give the supervisor a stop timeout of 10 seconds or more.
+- **Logs**: `--log-file <path>` (or `PYNODE_LOG_FILE`) adds a rotating log file (10 MB, 5 backups) next to console output.
+- **Upload limit**: request bodies are capped at 4096 MB; change it with `PYNODE_MAX_UPLOAD_MB` (`0` = unlimited).
+- **TLS**: PyNode speaks plain HTTP. Terminate TLS in a reverse proxy (nginx, Caddy, Traefik) and disable response buffering for `/api/debug/stream` and the MJPEG routes, which are long-lived streams.
+- **Persistent data**: keep the data directory (`--data-dir`, workflows and credentials) and the models directory (`--models-dir`, downloaded weights) on persistent storage. See [DOCKER.md](DOCKER.md) for the container setup.
+
 ## Docker Setup
 
 PyNode can be run in a Docker container with GPU support (CUDA 12.6).

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/docker-compose.yml

@@ -14,11 +14,19 @@ services:
     volumes:
       # Mount persistent data
       - ./workflows:/app/workflows
+      - ./models:/app/models
       - ./logs:/app/logs
     environment:
       - PYTHONUNBUFFERED=1
+      - PYNODE_LOG_FILE=/app/logs/pynode.log
+      # Keep Hugging Face downloads (Re-ID / VLM weights) on the models volume
+      - HF_HOME=/app/models/huggingface
+      # Strongly recommended whenever the port is reachable from other machines:
+      - PYNODE_API_KEY=${PYNODE_API_KEY:-}
       - HOST_IP=${HOST_IP:-}
     restart: unless-stopped
+    # PyNode stops every workflow on SIGTERM so recordings and logs are finalised.
+    stop_grace_period: 30s
     # Rotate container logs so they cannot fill the host disk
     logging:
       driver: json-file

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/docker-entrypoint.sh

@@ -3,7 +3,7 @@ set -e
 
 # Ensure bind-mounted directories are writable by appuser (uid 1000).
 # docker-compose mounts host directories that may be owned by root.
-for dir in /app/workflows /app/workflows/services /app/logs; do
+for dir in /app/workflows /app/workflows/services /app/logs /app/models; do
     mkdir -p "$dir"
     chown -R 1000:1000 "$dir" 2>/dev/null || true
 done

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/docs/CREATING_NODES.md

@@ -246,6 +246,45 @@ Properties define the configuration UI shown when a node is selected.
 }
 ```
 
+### Credential (stored secret)
+
+Never put a secret (token, password, API key) in a `text` property. Node config is saved as plain text in `workflow.json`, its backups and exports, and is sent to the editor. Use a `credential` property instead: the config then holds only a credential ID, while the secret is stored encrypted in the credential store and never sent back to the browser.
+
+```python
+{
+    'name': 'credential',
+    'label': 'Credential',
+    'type': 'credential',
+    'credentialType': 'secret'   # core type: one secret value
+}
+```
+
+Resolve it when you need the value, and keep the result in memory only (never in `self.config`, a message or a log line):
+
+```python
+from pynode.nodes.base_node import CredentialError
+
+try:
+    token = self.get_credential(self.config.get('credential'))['value']
+except CredentialError as e:
+    self.report_error(str(e))   # not found, store locked, or wrong key
+    return
+```
+
+For the core `secret` type, `self.get_secret()` does the lookup for you and raises `CredentialError` if the credential is of another type. Give it the name of a legacy plain-text property when you are converting an existing node, so flows saved before the change keep working. A selected credential that cannot be resolved raises and never falls back to the legacy value:
+
+```python
+try:
+    token = self.get_secret('credential', legacy_key='api_key')   # '' when neither is set
+except CredentialError as e:
+    self.report_error(str(e))
+    return
+```
+
+Libraries often quote a secret in their error messages (for example in a request URL), so remove it from any exception text before you report or log it.
+
+Node packages can register their own credential types (for example a username plus a password) with `pynode.credential_store.register_credential_type()`.
+
 ### Conditional Visibility (`showIf`)
 
 Show a property only when another property has a specific value:
@@ -689,6 +728,8 @@ class InternalNode(BaseNode):
 4. **Using hardcoded strings** - Use `MessageKeys.PAYLOAD` not `'payload'`, etc.
 5. **Not handling `None` payloads** - Always provide defaults: `msg.get(MessageKeys.PAYLOAD, default)`.
 6. **Blocking in `on_input`** - Long operations block the worker thread. For CPU-bound work, consider additional threads.
+7. **Doing heavy work in a sink's `on_input_direct`** - It runs on the *sending* node's thread for every message, so slow work there (encoding, disk or network I/O) caps the frame rate of the node feeding it. Keep it to storing a reference and do the work on your own thread or when the result is requested.
+8. **Setting `shares_input = True` on a node that modifies or forwards its input** - That flag lets `send()` skip the fan-out copy for read-only nodes. A node that mutates the payload or sends it on must leave it `False`.
 7. **Putting the class in the wrong folder** - The folder must be directly under `pynode/nodes/`, not nested deeper.
 8. **Class name not ending in `Node`** - Auto-discovery filters by this suffix.
 9. **Circular imports** - Only import from `pynode.nodes.base_node`. Don't import other node types.

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/docs/EXTENSIBILITY.md

@@ -202,28 +202,31 @@ class BaseNode:
 
 ### Queue Management
 
-Messages are enqueued with optional dropping:
-
-```python
-def receive(self, msg: Dict[str, Any], input_index: int = 0):
-    """Receive a message on an input."""
-    if not self.enabled:
-        return
-    
-    # Add queue length metadata
-    msg[MessageKeys.QUEUE_LENGTH] = self._message_queue.qsize()
-    
-    try:
-        if self.drop_while_busy and self._processing:
-            # Drop message if node is busy
-            self.drop_count += 1
-            return
-        
-        # Enqueue message (blocks if queue is full)
-        self._message_queue.put((deepcopy(msg), input_index))
-    except queue.Full:
-        self.drop_count += 1
-```
+Delivery is decided per recipient inside `BaseNode.send()`:
+
+| Recipient | What happens |
+|---|---|
+| Sink with `on_input_direct` (no outputs) | Called synchronously **on the sending node's thread**. |
+| Idle node | Message is put on the node's queue; its worker thread wakes immediately. |
+| Busy node, `drop_messages` on | Message is parked in a one-slot, latest-wins inbox (one slot per input port). A newer message replaces it and `drop_count` is incremented. When the node finishes, it continues straight away with the newest message. |
+| Busy node, `drop_messages` off | Message is queued (up to 1000). |
+
+Copies are made only where a branch could otherwise see another branch's changes:
+
+- one recipient: no copy, the recipient takes over the sender's objects;
+- several recipients: each gets its own `deepcopy`, except
+  - nodes that declare `shares_input = True` (they only read the message and never
+    forward its objects, e.g. Image Viewer and Rate Probe), which share the original, and
+  - busy nodes, whose copy is made later on their own worker thread and only for the
+    messages they actually process.
+
+Two consequences for node authors:
+
+- A sink's `on_input_direct` runs on the upstream node's thread for every message, so
+  anything slow there throttles the source. Store what you need and do the heavy work
+  elsewhere (the Image Viewer keeps a reference and encodes when the UI asks for a frame).
+- Set `shares_input = True` only if the node never mutates anything reachable from the
+  incoming message and never passes those objects downstream.
 
 ### Connection Routing
 

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/examples/camera_workflow.py

@@ -4,13 +4,11 @@ This example runs without the UI - it creates nodes programmatically,
 connects them, and displays the output in an OpenCV window.
 """
 
-import sys
-import os
 import time
 import cv2
 import numpy as np
 import base64
-from typing import Dict, Any
+from typing import Any
 
 from pynode.workflow_engine import WorkflowEngine
 from pynode.nodes.base_node import BaseNode, MessageKeys
@@ -47,7 +45,7 @@ class DisplayNode(BaseNode):
         cv2.destroyWindow(self.window_name)
         print(f"[{self.name}] Display window closed")
     
-    def on_input(self, msg: Dict[str, Any], input_index: int = 0):
+    def on_input(self, msg: dict[str, Any], input_index: int = 0):
         """
         Process incoming image messages and display them.
         """

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/examples/camera_yolo_workflow.py

@@ -4,13 +4,11 @@ and displays the annotated results using OpenCV.
 This example runs without the UI - it creates nodes programmatically.
 """
 
-import sys
-import os
 import time
 import cv2
 import numpy as np
 import base64
-from typing import Dict, Any
+from typing import Any
 
 from pynode.workflow_engine import WorkflowEngine
 from pynode.nodes.base_node import BaseNode, MessageKeys
@@ -48,7 +46,7 @@ class DisplayNode(BaseNode):
         cv2.destroyWindow(self.window_name)
         print(f"[{self.name}] Display window closed")
     
-    def on_input(self, msg: Dict[str, Any], input_index: int = 0):
+    def on_input(self, msg: dict[str, Any], input_index: int = 0):
         """
         Process incoming image messages and display them.
         """

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/pynode/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.8'
-__version_tuple__ = version_tuple = (0, 2, 8)
+__version__ = version = '0.2.9'
+__version_tuple__ = version_tuple = (0, 2, 9)
 
-__commit_id__ = commit_id = 'g7b8eff347'
+__commit_id__ = commit_id = 'gdd99cab55'

{pynode_flow-0.2.8 → pynode_flow-0.2.9}/pynode/api/__init__.py

@@ -1,12 +1,15 @@
 """API blueprints for the PyNode Flask server."""
 
+from pynode.api.credentials import credentials_bp
+from pynode.api.health import health_bp
 from pynode.api.nodes import nodes_bp
 from pynode.api.services import services_bp
 from pynode.api.sse import sse_bp
 from pynode.api.uploads import uploads_bp
 from pynode.api.workflows import workflows_bp
 
-ALL_BLUEPRINTS = (workflows_bp, nodes_bp, services_bp, uploads_bp, sse_bp)
+ALL_BLUEPRINTS = (workflows_bp, nodes_bp, services_bp, credentials_bp, uploads_bp, sse_bp,
+                  health_bp)
 
 
 def register_blueprints(app):