pynode-flow 0.2.0__py3-none-any.whl

pynode/__init__.py

@@ -0,0 +1,37 @@
+"""
+PyNode - A Node-RED-like Visual Workflow System with Python Backend
+"""
+
+# Tune CPU thread pools before heavy libraries (torch/OpenMP) initialise, so
+# the OMP_WAIT_POLICY change takes effect. See pynode._perf for rationale.
+from pynode._perf import configure_inference_threads
+
+configure_inference_threads()
+
+from pynode.workflow_engine import WorkflowEngine
+
+
+def _resolve_version() -> str:
+    """Best-effort package version.
+
+    Prefers the installed distribution metadata (the authoritative version for
+    a `pip install`), then the file setuptools_scm writes at build time, and
+    finally a placeholder for a bare source checkout that was never built.
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version("pynode-flow")
+        except PackageNotFoundError:
+            pass
+    except Exception:
+        pass
+    try:
+        from pynode._version import __version__ as _scm_version  # generated by setuptools_scm
+        return _scm_version
+    except Exception:
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+__all__ = ['WorkflowEngine', '__version__']

pynode/__main__.py

@@ -0,0 +1,9 @@
+"""
+PyNode package entry point for module execution.
+Enables running: python -m pynode
+"""
+
+from pynode.main import main
+
+if __name__ == '__main__':
+    main()

pynode/_perf.py

@@ -0,0 +1,65 @@
+"""CPU thread-pool tuning for GPU-backed inference.
+
+The heavy model math runs on the GPU (CUDA / OpenVINO), but every frame still
+triggers small CPU-side pre/post-processing ops around it: letterbox resize,
+NMS, tensor -> numpy conversions, and result drawing. PyTorch and OpenCV each
+default their thread pool to span *every* core, and OpenMP's default wait
+policy is ACTIVE (busy-spin), so those pools keep spinning between the tiny
+per-frame ops and peg the CPU even though the GPU does the real work.
+
+These ops are latency-bound, not throughput-bound, so a wide pool buys nothing
+and only adds spin overhead. We cap the pools and disable the busy-spin.
+
+Call configure_inference_threads() as early as possible - before torch/OpenMP
+initialise - so the OMP_WAIT_POLICY change takes effect.
+
+Overridable via PYNODE_INFERENCE_THREADS (e.g. set it higher when you actually
+run a plain .pt model on the CPU *device* and want torch to use more cores;
+GPU / OpenVINO inference is unaffected by this cap, which only touches the
+light pre/post-processing).
+"""
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+# Pre/post-processing ops are small and latency-bound; a handful of threads is
+# plenty and avoids the all-cores busy-spin that dominates CPU during GPU runs.
+_DEFAULT_THREADS = 4
+
+
+def _thread_cap() -> int:
+    override = os.environ.get("PYNODE_INFERENCE_THREADS")
+    if override:
+        try:
+            return max(1, int(override))
+        except ValueError:
+            logger.warning(
+                "Invalid PYNODE_INFERENCE_THREADS=%r; using default", override
+            )
+    cpu = os.cpu_count() or _DEFAULT_THREADS
+    return min(_DEFAULT_THREADS, cpu)
+
+
+def configure_inference_threads() -> None:
+    """Cap torch/OpenCV CPU thread pools and disable OpenMP busy-spin."""
+    # Must be set before the OpenMP runtime initialises (i.e. before torch is
+    # imported) for the worker threads to stop busy-spinning between ops.
+    os.environ.setdefault("OMP_WAIT_POLICY", "PASSIVE")
+
+    cap = _thread_cap()
+
+    try:
+        import torch
+
+        torch.set_num_threads(cap)
+    except Exception as e:  # torch may be optional / not importable yet
+        logger.debug("Could not cap torch threads: %s", e)
+
+    try:
+        import cv2
+
+        cv2.setNumThreads(cap)
+    except Exception as e:
+        logger.debug("Could not cap OpenCV threads: %s", e)

pynode/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = 'g92a665661'

pynode/api/__init__.py

@@ -0,0 +1,15 @@
+"""API blueprints for the PyNode Flask server."""
+
+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)
+
+
+def register_blueprints(app):
+    """Register every API blueprint on the given Flask app."""
+    for bp in ALL_BLUEPRINTS:
+        app.register_blueprint(bp)

pynode/api/helpers.py

@@ -0,0 +1,79 @@
+"""Shared helpers for the API blueprints.
+
+Route handlers access the per-app WorkflowManager through ``_get_manager()``,
+which reads it off ``current_app`` - so every blueprint works against
+whichever app instance is handling the request (default instance or a fresh
+``create_app()`` app in tests).
+"""
+
+from flask import current_app, jsonify, request
+
+_INVALID_BODY_ERROR = 'Invalid or missing JSON body'
+
+
+def _get_manager():
+    """Return the WorkflowManager of the app handling the current request."""
+    return current_app.extensions['workflow_manager']
+
+
+def _json_error(message, status):
+    """JSON error envelope: {'success': False, 'error': str}."""
+    return jsonify({'success': False, 'error': message}), status
+
+
+def _get_json_body(required=True):
+    """Parse the request body as a JSON object.
+
+    Returns a dict on success. Returns None when the body is invalid: not
+    parseable JSON, not a JSON object, or missing while ``required`` is True.
+    A missing/empty body with ``required=False`` yields ``{}``.
+    """
+    data = request.get_json(silent=True)
+    if data is None:
+        # get_json(silent=True) is None for both "no body" and "bad JSON";
+        # treat any non-empty unparseable body as invalid even when optional.
+        if required or request.get_data(cache=True):
+            return None
+        return {}
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _get_workflow_id_from_request():
+    """Extract workflow_id from request query params, defaulting to active."""
+    manager = _get_manager()
+    with manager.state_lock:
+        return request.args.get('workflow', manager.active_workflow_id)
+
+
+def _get_working_engine(workflow_id=None):
+    """Get working engine for a workflow, defaulting to active."""
+    return _get_manager().get_working_engine(workflow_id)
+
+
+def _get_deployed_engine(workflow_id=None):
+    """Get deployed engine for a workflow, defaulting to active."""
+    return _get_manager().get_deployed_engine(workflow_id)
+
+
+def _find_deployed_node(node_id):
+    """Find a node across all deployed engines. Returns (node, workflow_id) or (None, None)."""
+    return _get_manager().find_deployed_node(node_id)
+
+
+def _resolve_node_handler(node_id, handler_name):
+    """Resolve a deployed node and one of its callable handler methods.
+
+    Returns (node, method, error_response). On success error_response is None;
+    on failure node/method are None and error_response is a (json, status) tuple.
+    """
+    node, _ = _find_deployed_node(node_id)
+    if not node:
+        return None, None, (jsonify({'success': False, 'error': 'Node not found'}), 404)
+
+    method = getattr(node, handler_name, None)
+    if method is None or not callable(method):
+        return None, None, (jsonify({'success': False, 'error': f'Node does not support {handler_name}'}), 400)
+
+    return node, method, None

pynode/api/nodes.py

@@ -0,0 +1,423 @@
+"""Node API: node-types listing, node CRUD, position, enabled state,
+connections, declared button actions, and the dynamic per-node-type routes
+that node classes declare via ``api_routes``.
+"""
+
+import inspect
+import os
+
+from flask import Blueprint, Response, jsonify, request, stream_with_context
+
+from pynode import node_registry
+from pynode.api.helpers import (
+    _INVALID_BODY_ERROR,
+    _find_deployed_node,
+    _get_json_body,
+    _get_manager,
+    _get_working_engine,
+    _get_workflow_id_from_request,
+    _json_error,
+    _resolve_node_handler,
+)
+
+nodes_bp = Blueprint('nodes', __name__)
+
+
+@nodes_bp.route('/api/node-types', methods=['GET'])
+def get_node_types():
+    """Get all available node types (excluding system nodes like ErrorNode)."""
+    return jsonify(node_registry.get_node_types())
+
+
+@nodes_bp.route('/api/nodes', methods=['GET'])
+def get_nodes():
+    """Get all nodes in the working workflow."""
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+    node_list = [node.to_dict() for node in engine.nodes.values()]
+    return jsonify(node_list)
+
+
+@nodes_bp.route('/api/nodes', methods=['POST'])
+def create_node():
+    """Create a new node in working workflow."""
+    data = _get_json_body()
+    if data is None:
+        return _json_error(_INVALID_BODY_ERROR, 400)
+    node_type = data.get('type')
+    node_id = data.get('id')
+    name = data.get('name', '')
+    config = data.get('config', {})
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+
+    try:
+        node = engine.create_node(node_type, node_id, name, config)
+        # Set position if provided
+        if 'x' in data:
+            node.x = data.get('x', 0)
+        if 'y' in data:
+            node.y = data.get('y', 0)
+        return jsonify(node.to_dict()), 201
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+@nodes_bp.route('/api/nodes/<node_id>', methods=['GET'])
+def get_node(node_id):
+    """Get a specific node from working workflow."""
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+    node = engine.get_node(node_id)
+    if node:
+        return jsonify(node.to_dict())
+    return jsonify({'success': False, 'error': 'Node not found'}), 404
+
+
+@nodes_bp.route('/api/nodes/<node_id>', methods=['PUT'])
+def update_node(node_id):
+    """Update a node's configuration in working workflow."""
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+    node = engine.get_node(node_id)
+    if not node:
+        return jsonify({'success': False, 'error': 'Node not found'}), 404
+
+    data = _get_json_body()
+    if data is None:
+        return _json_error(_INVALID_BODY_ERROR, 400)
+
+    if 'name' in data:
+        node.name = data['name']
+    if 'config' in data:
+        node.configure(data['config'])
+    if 'enabled' in data:
+        node.enabled = data['enabled']
+
+    return jsonify(node.to_dict())
+
+
+@nodes_bp.route('/api/nodes/<node_id>', methods=['DELETE'])
+def delete_node(node_id):
+    """Delete a node from working workflow."""
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+    try:
+        engine.delete_node(node_id)
+        return '', 204
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+@nodes_bp.route('/api/nodes/<node_id>/position', methods=['PUT'])
+def update_node_position(node_id):
+    """Update a node's position in working workflow."""
+    data = _get_json_body()
+    if data is None:
+        return _json_error(_INVALID_BODY_ERROR, 400)
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+    try:
+        node = engine.nodes.get(node_id)
+        if not node:
+            return jsonify({'success': False, 'error': 'Node not found'}), 404
+
+        node.x = data.get('x', 0)
+        node.y = data.get('y', 0)
+        return jsonify({'success': True})
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+@nodes_bp.route('/api/nodes/<node_id>/enabled', methods=['POST'])
+def set_node_enabled(node_id):
+    """Set node enabled state (doesn't require redeployment)."""
+    manager = _get_manager()
+    data = _get_json_body()
+    if data is None:
+        return _json_error(_INVALID_BODY_ERROR, 400)
+    enabled = data.get('enabled', True)
+
+    try:
+        # Update BOTH working and deployed engines so state is preserved.
+        # Snapshot engine references under the lock, then work on them outside.
+        with manager.state_lock:
+            engine_pairs = [
+                (manager.working_engines.get(wid), manager.deployed_engines.get(wid))
+                for wid in manager.workflows
+            ]
+
+        for working, deployed in engine_pairs:
+            working_node = working.nodes.get(node_id) if working else None
+            deployed_node = deployed.nodes.get(node_id) if deployed else None
+
+            if working_node:
+                working_node.enabled = enabled
+            if deployed_node:
+                deployed_node.enabled = enabled
+
+        # Save workflow to persist the state
+        manager.save_workflow_to_disk()
+
+        return jsonify({'success': True, 'enabled': enabled})
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+@nodes_bp.route('/api/nodes/<node_id>/enabled', methods=['GET'])
+def get_node_enabled(node_id):
+    """Get node enabled state."""
+    manager = _get_manager()
+    try:
+        # Search all workflows for this node (snapshot refs under the lock)
+        with manager.state_lock:
+            engine_pairs = [
+                (manager.working_engines.get(wid), manager.deployed_engines.get(wid))
+                for wid in manager.workflows
+            ]
+
+        node = None
+        for working, deployed in engine_pairs:
+            node = ((deployed.nodes.get(node_id) if deployed else None)
+                    or (working.nodes.get(node_id) if working else None))
+            if node:
+                break
+
+        if not node:
+            return jsonify({'success': False, 'error': 'Node not found'}), 404
+
+        return jsonify({'enabled': node.enabled})
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+@nodes_bp.route('/api/connections', methods=['POST'])
+def create_connection():
+    """Create a connection between two nodes in working workflow."""
+    data = _get_json_body()
+    if data is None:
+        return _json_error(_INVALID_BODY_ERROR, 400)
+    source_id = data.get('source')
+    target_id = data.get('target')
+    source_output = data.get('sourceOutput', 0)
+    target_input = data.get('targetInput', 0)
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+
+    try:
+        engine.connect_nodes(source_id, target_id, source_output, target_input)
+        return jsonify({
+            'source': source_id,
+            'target': target_id,
+            'sourceOutput': source_output,
+            'targetInput': target_input
+        }), 201
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+@nodes_bp.route('/api/connections', methods=['DELETE'])
+def delete_connection():
+    """Delete a connection between two nodes in working workflow."""
+    data = _get_json_body()
+    if data is None:
+        return _json_error(_INVALID_BODY_ERROR, 400)
+    source_id = data.get('source')
+    target_id = data.get('target')
+    source_output = data.get('sourceOutput', 0)
+    wid = _get_workflow_id_from_request()
+    engine = _get_working_engine(wid)
+    if not engine:
+        return jsonify({'success': False, 'error': 'Workflow not found'}), 404
+
+    try:
+        engine.disconnect_nodes(source_id, target_id, source_output)
+        return '', 204
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 400
+
+
+def _get_declared_actions(node):
+    """Collect the union of 'actions' declared across the node's class hierarchy."""
+    declared = set()
+    for klass in type(node).__mro__:
+        declared.update(getattr(klass, 'actions', None) or [])
+    return declared
+
+
+def _action_accepts_arg(method):
+    """Return True if `method` accepts at least one positional argument."""
+    try:
+        sig = inspect.signature(method)
+    except (TypeError, ValueError):
+        return False
+    for param in sig.parameters.values():
+        if param.kind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD,
+                          param.VAR_POSITIONAL):
+            return True
+    return False
+
+
+@nodes_bp.route('/api/nodes/<node_id>/<action>', methods=['POST'])
+def trigger_node_action(node_id, action):
+    """Trigger a button action on a node in deployed workflow.
+
+    Only actions explicitly declared in the node class's `actions` list may be
+    invoked; anything else (including private/underscore names) returns 404.
+
+    Actions may optionally accept a single value supplied via a JSON body
+    ``{"value": ...}`` (e.g. VideoReaderNode.seek(target)); zero-argument
+    actions are called with no arguments.
+    """
+    try:
+        node, _ = _find_deployed_node(node_id)
+        if not node:
+            return jsonify({'success': False, 'error': 'Node not found'}), 404
+
+        # Only allow explicitly declared, public action names
+        if action.startswith('_') or action not in _get_declared_actions(node):
+            return jsonify({'success': False, 'error': f'Action {action} not found on node'}), 404
+
+        method = getattr(node, action, None)
+        if not callable(method):
+            return jsonify({'success': False, 'error': f'{action} is not a callable method'}), 400
+
+        data = request.get_json(silent=True)
+        if (isinstance(data, dict) and 'value' in data
+                and _action_accepts_arg(method)):
+            method(data['value'])
+        else:
+            method()
+        return jsonify({'success': True, 'status': 'success', 'action': action})
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+# ==============================================================================
+# Dynamic node endpoint registration (from node-class ``api_routes``)
+# ==============================================================================
+
+def _add_node_route(route, view_func, endpoint_name, methods):
+    """Register a URL rule under the standard node API prefix."""
+    nodes_bp.add_url_rule(
+        f'/api/nodes/<node_id>/{route}',
+        endpoint=endpoint_name,
+        view_func=view_func,
+        methods=methods
+    )
+
+
+def _register_json_route(route, methods, handler_name, endpoint_name):
+    """Register a standard JSON API route."""
+    def handler(node_id):
+        _, method, error = _resolve_node_handler(node_id, handler_name)
+        if error:
+            return error
+        try:
+            result = method()
+            if result is None:
+                return '', 204
+            return jsonify(result)
+        except Exception as e:
+            return jsonify({'success': False, 'error': str(e)}), 500
+
+    _add_node_route(route, handler, endpoint_name, methods)
+
+
+def _register_file_upload_route(route, methods, handler_name, endpoint_name, allowed_extensions):
+    """Register a file upload API route."""
+    def handler(node_id):
+        _, method, error = _resolve_node_handler(node_id, handler_name)
+        if error:
+            # Re-shape error payload to the success/error contract used by uploads
+            payload, status = error
+            return jsonify({'success': False, 'error': payload.get_json()['error']}), status
+
+        if 'file' not in request.files:
+            return jsonify({'success': False, 'error': 'No file provided'}), 400
+
+        file = request.files['file']
+        if not file.filename or file.filename == '':
+            return jsonify({'success': False, 'error': 'No file selected'}), 400
+
+        if allowed_extensions:
+            ext = os.path.splitext(file.filename)[1].lower()
+            if ext not in allowed_extensions:
+                return jsonify({'success': False, 'error': f'Unsupported file type: {ext}'}), 400
+
+        try:
+            file_bytes = file.read()
+            result = method(file_bytes, file.filename)
+            return jsonify(result)
+        except Exception as e:
+            return jsonify({'success': False, 'error': str(e)}), 500
+
+    _add_node_route(route, handler, endpoint_name, methods)
+
+
+def _register_stream_route(route, handler_name, endpoint_name):
+    """Register an MJPEG stream route."""
+    def handler(node_id):
+        _, method, error = _resolve_node_handler(node_id, handler_name)
+        if error:
+            return error
+
+        def generate():
+            for img_data in method():
+                yield (b'--frame\r\n'
+                       b'Content-Type: image/jpeg\r\n\r\n' + img_data + b'\r\n')
+
+        return Response(
+            stream_with_context(generate()),
+            mimetype='multipart/x-mixed-replace; boundary=frame'
+        )
+
+    _add_node_route(route, handler, endpoint_name, ['GET'])
+
+
+def _register_dynamic_node_routes():
+    """Register routes for all node types that declare api_routes."""
+    registered = set()
+
+    for node_type_name, routes in node_registry.api_route_registry.items():
+        for route_def in routes:
+            route = route_def['route']
+            methods = route_def.get('methods', ['GET'])
+            handler_name = route_def['handler']
+            route_type = route_def.get('type', 'json')
+
+            # Create a unique endpoint name for Flask
+            # Combine methods to handle same route with different methods
+            methods_key = '_'.join(sorted(methods))
+            endpoint_name = f"node_{node_type_name}_{route}_{methods_key}"
+
+            if endpoint_name in registered:
+                continue
+            registered.add(endpoint_name)
+
+            if route_type == 'file_upload':
+                allowed_ext = route_def.get('allowed_extensions', set())
+                _register_file_upload_route(route, methods, handler_name, endpoint_name, allowed_ext)
+            elif route_type == 'stream':
+                _register_stream_route(route, handler_name, endpoint_name)
+            else:
+                _register_json_route(route, methods, handler_name, endpoint_name)
+
+
+# Register all dynamic routes on the blueprint at import time (node classes
+# are static); every app the blueprint is registered on gets them.
+_register_dynamic_node_routes()