pynode-flow 0.2.4__tar.gz → 0.2.6__tar.gz

{pynode_flow-0.2.4 → pynode_flow-0.2.6}/.gitignore

@@ -196,3 +196,6 @@ checkpoints/
 output/
 output_low/
 output_not/
+
+# Working prompt / plan files (local scratch, not part of the project)
+*.prompt.md

{pynode_flow-0.2.4 → pynode_flow-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pynode-flow
-Version: 0.2.4
+Version: 0.2.6
 Summary: Python based Node-RED-like visual workflow system
 Author: olkham
 License-Expression: MIT
@@ -76,26 +76,41 @@ https://github.com/user-attachments/assets/0b53085a-2cc6-4c26-bd43-e0de1e0716a2
 - **Fully Extensible**: Third-party nodes can be added without modifying core code
 - **UI Components**: Nodes can define interactive controls (buttons, toggles, displays) in their cards
 - **Node-RED Compatible Messages**: Message structure with `payload` and `topic` fields
-- **Built-in Nodes**:
-  - **InjectNode**: Generate messages with configurable payloads
-  - **FunctionNode**: Execute custom Python code on messages
-  - **DebugNode**: Display messages in the debug panel
-  - **ChangeNode**: Modify message properties
-  - **SwitchNode**: Route messages based on conditions
-  - **DelayNode**: Delay message delivery
-  - **GateNode**: Control message flow with real-time toggle
-  - **LinkNode**: Pass messages between flows via named channels (Link In / Link Out)
-  - **RateProbeNode**: Monitor message throughput
-  - **QueueLengthProbeNode**: Monitor queue lengths
-  - **CounterNode**: Count messages
-  - **MQTTNode**: MQTT communication
-  - **MessageWriterNode**: Save message data
-  - **VideoWriterNode**: Save video output
-  - **Vision Nodes**: Camera input, YOLO detection, tracking, image processing, display, and file output
+- **Multiple Workspaces**: Several independent flows, each with its own deploy/run state
 - **REST API**: Complete API for programmatic workflow management
 - **Export/Import**: Save and load workflows as JSON
 - **Dynamic Properties**: Node properties and UI components defined in node classes
 
+### Built-in Nodes
+
+Around 85 node types ship with PyNode, grouped by palette category. Every node
+carries its own documentation in the editor's **Information** panel (ℹ️ tab).
+
+| Category | Nodes |
+| --- | --- |
+| **Common** | Inject, Debug, Link In / Link Out (named channels between flows) |
+| **Function** | Function (custom Python), Change, Filter, Delay, Batch, Join, Split, Range, Slider |
+| **Input** | Camera, Frame Source, Video Reader, Image Upload, Message Reader, Omron Camera |
+| **Output** | Image Viewer, Image Writer, Video Writer, Message Writer, Roboflow Upload |
+| **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, Tracker, Supervision Tracker, Crop, Slice Image / Slice Collector, Draw Predictions, Confidence Filter, Label Filter, Merge Predictions, Image Format, Qwen3-VL, vLLM |
+| **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 |
+
+Highlights:
+
+- **Slider** — an interactive on-card slider that stamps a live value onto any
+  `msg` path; drag it and downstream nodes update immediately.
+- **UDP In / Out, TCP In / Out** — move messages (including video frames)
+  between PyNode instances or to anything else that speaks the wire format.
+  Their Information panel contains a ready-made **Node-RED flow you can copy
+  and import**, pre-set to the node's port.
+- **Video Reader** — video-file playback with on-card transport controls.
+- **Inference** — a multi-backend inference node (ONNX Runtime, Ultralytics)
+  that discovers available engines at startup.
+
 ## Quick Start
 
 ### Install from PyPI (recommended for users)
@@ -116,7 +131,7 @@ pynode
 or specify a port:
 
 ```bash
-pynode --port 500
+pynode --port 8080
 ```
 
 See [INSTALL.md](INSTALL.md) for the full list of extras (`vision`, `mqtt`,
@@ -196,10 +211,11 @@ Navigate to `http://localhost:5000`
 
 ### Load an Example Workflow
 
-Ten ready-made learning workflows ship with PyNode — from a two-node hello
+Twelve ready-made learning workflows ship with PyNode — from a two-node hello
 world up to a camera → YOLO → filter → MQTT alert pipeline (including a "blur
-every detected person" privacy flow). Load any of them straight from the
-editor: **☰ menu → Examples → pick one**, then press **Deploy**. See
+every detected person" privacy flow, a UDP socket bridge and a slider-driven
+crop). Load any of them straight from the editor: **☰ menu → Examples → pick
+one**, then press **Deploy**. See
 [pynode/static/examples/README.md](pynode/static/examples/README.md) for the
 guided tour and per-example prerequisites.
 
@@ -289,58 +305,53 @@ PyNode is designed to be easily extended with custom nodes:
 ```text
 pynode/                     # Project root
 ├── pynode/                 # Main package
-│   ├── __init__.py
 │   ├── __main__.py         # Entry point for 'python -m pynode'
 │   ├── _version.py         # Version (generated by setuptools_scm at build)
 │   ├── main.py             # CLI application
-│   ├── server.py           # Flask REST API with SSE support
-│   ├── workflow_engine.py  # Workflow management
-│   ├── models/             # ML model storage
+│   ├── config.py           # Data/models directory resolution
+│   ├── server.py           # Flask app factory, static routes, auth
+│   ├── node_registry.py    # Node type discovery and metadata cache
+│   ├── workflow_engine.py  # Message routing and node execution
+│   ├── workflow_manager.py # Multiple workflows, persistence and backups
+│   ├── install_nodes.py    # 'pynode-install-nodes' per-node dependency installer
+│   ├── api/                # REST API blueprints
+│   │   ├── nodes.py        # Node CRUD, actions, frames, uploads
+│   │   ├── workflows.py    # Workflow + multi-workflow endpoints
+│   │   ├── services.py     # Shared services (MQTT brokers)
+│   │   ├── sse.py          # Server-sent events (debug stream)
+│   │   └── uploads.py
 │   ├── nodes/              # Node implementations (each in its own folder)
-│   │   ├── __init__.py
 │   │   ├── base_node.py    # BaseNode class
+│   │   ├── info.py         # Info builder for node help panels
+│   │   ├── messages.py     # Message construction helpers
 │   │   ├── InjectNode/     # Generate messages
 │   │   ├── FunctionNode/   # Custom Python code
-│   │   ├── DebugNode/      # Debug output
-│   │   ├── ChangeNode/     # Modify messages
-│   │   ├── SwitchNode/     # Route based on conditions
-│   │   ├── DelayNode/      # Delay messages
-│   │   ├── GateNode/       # Control message flow
-│   │   ├── RateProbeNode/  # Monitor throughput
-│   │   ├── QueueLengthProbeNode/  # Monitor queue lengths
-│   │   ├── CounterNode/    # Count messages
-│   │   ├── CameraNode/     # Camera input
+│   │   ├── SocketNode/     # UDP/TCP nodes + Node-RED interop flow
 │   │   ├── UltralyticsNode/ # YOLO detection
-│   │   ├── ImageViewerNode/ # Display images
-│   │   ├── ImageWriterNode/ # Save images
-│   │   ├── TrackerNode/    # Object tracking
-│   │   ├── MQTTNode/       # MQTT communication
-│   │   ├── MessageWriterNode/ # Save message data
-│   │   ├── VideoWriterNode/   # Save video
-│   │   ├── OpenCV/         # OpenCV operations
-│   │   └── ...             # 30+ other node types
+│   │   ├── InferenceNode/  # Multi-backend inference engines
+│   │   ├── OpenCV/         # ~28 OpenCV operations
+│   │   └── ...             # ~50 node folders in total
 │   └── static/             # Web UI
 │       ├── index.html
 │       ├── style.css
-│       ├── js/             # JavaScript modules
-│       │   ├── nodes.js
-│       │   ├── events.js
-│       │   ├── connections.js
-│       │   ├── debug.js
+│       ├── js/             # JavaScript modules (ES modules, no build step)
+│       │   ├── main.js     # Entry point
+│       │   ├── nodes.js    # Node rendering
+│       │   ├── properties.js  # Properties panel
+│       │   ├── selection.js   # Selection + Information panel
 │       │   └── ...
+│       ├── examples/       # Bundled example workflows + manifest.json
 │       └── images/         # UI assets
-├── examples/               # Example workflows and tutorials
-│   ├── camera_workflow.py
-│   ├── camera_yolo_workflow.py
-│   └── README.md
-├── readmes/                # Extended documentation
-├── models/                 # ML models (YOLO, etc.)
+├── tests/                  # pytest suite
+├── examples/               # Programmatic (Python API) examples
 ├── docs/                   # Documentation files
 │   ├── CUSTOM_NODES.md     # Guide to creating custom nodes
+│   ├── CREATING_NODES.md   # Node authoring reference
 │   ├── UI_COMPONENTS.md    # Guide to node UI components
 │   └── EXTENSIBILITY.md    # Extensibility overview
-├── _backup/                # Workflow backups
-├── setup.py                # Package installation
+├── workflows/              # Persisted workflows (workflow.json + _backups/)
+├── models/                 # Downloaded/exported model weights
+├── setup.py                # Shim; metadata lives in pyproject.toml
 ├── setup.bat / setup.sh    # Setup scripts
 ├── requirements.txt        # Convenience installer (deps live in pyproject.toml)
 ├── pyproject.toml          # Package metadata, dependencies and build config
@@ -349,10 +360,12 @@ pynode/                     # Project root
 ├── docker-compose.yml      # Docker compose config
 ├── Dockerfile              # Docker build (CUDA)
 ├── Dockerfile.cpu          # Docker build (CPU only)
-├── README.md
-└── workflow.json           # Current workflow
+└── README.md
 ```
 
+> `workflows/` and `models/` are the defaults for a source checkout; both move
+> with `--data-dir` / `--models-dir` (see above).
+
 ## Creating Custom Nodes
 
 PyNode is fully extensible. All node information (visual properties, property schemas, and behavior) is contained within the node class itself. The main application has no hardcoded knowledge of specific node types.
@@ -423,28 +436,59 @@ Messages follow the Node-RED format:
 
 ## API Endpoints
 
+All `/api/` routes require the API key when the server is started with
+`--api-key` (see [Securing PyNode](#securing-pynode)).
+
+### Node types
+- `GET /api/node-types` - Palette metadata for every registered node type
+  (properties, colours, info HTML)
+
 ### Nodes
 - `GET /api/nodes` - List all nodes
 - `POST /api/nodes` - Create a node
 - `GET /api/nodes/<id>` - Get node details
 - `PUT /api/nodes/<id>` - Update node
 - `DELETE /api/nodes/<id>` - Delete node
-- `POST /api/nodes/<id>/<action>` - Trigger node action
+- `POST /api/nodes/<id>/<action>` - Trigger a node action (e.g. inject)
+- `GET|POST /api/nodes/<id>/enabled` - Read or set the node's enabled state
+- `PUT /api/nodes/<id>/position` - Move a node on the canvas
+- `GET /api/nodes/<id>/frame` - Latest frame from an image-producing node
+- `GET /api/nodes/<id>/stream` - MJPEG stream from an image-producing node
+- `GET /api/nodes/<id>/rate` - Throughput for a probe node
 
 ### Connections
 - `POST /api/connections` - Create connection
 - `DELETE /api/connections` - Delete connection
 
-### Workflow
+### Workflow (the active flow)
 - `GET /api/workflow` - Export workflow
 - `POST /api/workflow` - Import workflow
-- `POST /api/workflow/start` - Start workflow
-- `POST /api/workflow/stop` - Stop workflow
+- `POST /api/workflow/deploy-changes` - Deploy (optionally only modified nodes)
+- `POST /api/workflow/restart` - Restart the deployed workflow
+- `POST /api/workflow/stop` - Stop the deployed workflow
+- `POST /api/workflow/save` - Persist to disk
+- `GET /api/workflow/deployed` - The currently deployed definition
 - `GET /api/workflow/stats` - Get statistics
 
+### Workflows (multiple flows)
+- `GET /api/workflows` - List workflows
+- `POST /api/workflows` - Create a workflow
+- `PUT /api/workflows/<id>` - Rename/update a workflow
+- `DELETE /api/workflows/<id>` - Delete a workflow
+- `PUT /api/workflows/active` - Switch the active workflow
+
 ### Debug
 - `GET /api/nodes/<id>/debug` - Get debug messages
 - `DELETE /api/nodes/<id>/debug` - Clear debug messages
+- `GET /api/debug/stream` - Server-sent event stream of debug messages
+
+### Other
+- `GET /api/version` - Running PyNode version
+- `GET /api/link-channels` - Known Link In/Out channel names
+- `GET|POST /api/services/mqtt`, `GET|PUT|DELETE /api/services/mqtt/<id>`,
+  `POST /api/services/mqtt/test` - Shared MQTT broker definitions
+- `POST /api/upload/file`, `POST /api/nodes/<id>/upload_image`,
+  `POST /api/nodes/<id>/upload_video` - File uploads
 
 ## Example Programmatic Usage
 
@@ -479,12 +523,16 @@ print(messages)
 
 1. **Add Nodes**: Drag nodes from the palette onto the canvas
 2. **Connect Nodes**: Click an output port and drag to an input port
-3. **Configure Nodes**: Click a node to show its properties panel
+3. **Configure Nodes**: Click a node to show its properties panel; the **ℹ️
+   Information** tab in the right sidebar documents the selected node
 4. **Test Workflow**:
-   - Click **Start** to activate the workflow
+   - Click **Deploy** to activate the workflow (the ▼ menu offers Deploy
+     Modified / Full, Restart and Stop)
    - Use the **Inject** button on inject nodes to send messages
-   - View output in the debug panel at the bottom
-5. **Save/Load**: Use Export/Import buttons to save workflows
+   - View output in the **🐛 Debug** tab of the right sidebar
+5. **Multiple Flows**: Use the **+** tab to add another workspace; each flow
+   deploys and runs independently
+6. **Save/Load**: Use ☰ menu → Export / Import to save workflows as JSON
 
 ## Extending the System
 
@@ -528,7 +576,7 @@ Nodes can:
 - ⬜ SAM3 Node
 - ✅ REST Endpoint Node
 - ✅ Webhook Node
-- ⬜ UDP/TCP Node
+- ✅ UDP/TCP Node
 
 ### Example Flow Documentation Needed
 - ⬜ Bird seed level monitor
@@ -541,9 +589,64 @@ Nodes can:
 - ✅ YOLO: Add custom model support
 - ✅ YOLO: Add custom target HW string
 - ⬜ Roboflow: RF-DETR
-- ⬜ Roboflow: Upload images
+- ✅ Roboflow: Upload images
 - ⬜ DeepSort: Add option to use a different feature extractor model
 
+## Changelog
+
+Versions follow the `vX.Y.Z` git tags. The running build is shown next to the
+title in the editor and returned by `GET /api/version`.
+
+### 0.2.4
+
+**New nodes**
+
+- **UDP In / Out** and **TCP In / Out** (`SocketNode`) — move messages,
+  including video frames, between PyNode instances or any program that speaks
+  the wire format. UDP uses a chunked binary protocol (PNB1) for large
+  payloads; TCP uses newline-delimited JSON. Each node's Information panel
+  carries a **copy-and-import Node-RED flow** pre-set to that node's port,
+  with a worked interop example and a standalone `udp_probe.py` diagnostic in
+  `pynode/nodes/SocketNode/interop/`.
+- **Slider** (`ControlSliderNode`) — an interactive on-card slider that stamps
+  a live value onto any `msg` path, with *Send on Change* to emit while
+  dragging even with no input wired.
+
+**Improvements**
+
+- **Range** node: configurable output format.
+- **Crop** node: custom-path bbox source with format and coordinate-space
+  selectors.
+- **Image Upload** node: *Repeat Send* re-emits the image at a set rate (and
+  the pacing bug that capped 30fps at ~11fps is fixed).
+- **Function** node: built-in code templates.
+- Wider type hints, payload validation and error handling across nodes.
+- Docker: CUDA 12.6 runtime base image, version reporting, and better CUDA
+  detection in `setup.sh`.
+- Two new bundled examples: **UDP Socket Bridge** and **Slider-Driven Crop**.
+
+### 0.2.3
+
+- Performance: fewer message copies for nodes with a single output.
+- YOLO node: fixed model storage locations (weights now land in the models
+  directory rather than the working directory).
+
+### 0.2.2
+
+- **Link In / Link Out** nodes for passing messages between flows by channel
+  name.
+- Per-flow debug panel and per-flow run state.
+- Camera and rate-probe fixes; MQTT improvements.
+- The first bundled example workflows and general UI/UX fixes.
+
+### 0.2.1
+
+- Removed the end-of-life Geti node and its SDK dependency.
+
+### 0.2.0
+
+- First PyPI release as **`pynode-flow`**.
+
 ## License
 
 MIT License - Feel free to use and modify.