Add node groups for visual organization of related nodes

API_MIGRATION_GUIDE.md

@@ -370,7 +370,78 @@ nodz.api.signals.connection_created.connect(on_connection_created)
 
 ## New Features
 
-### 1. Enhanced Error Handling
+### 1. Node Groups API
+
+The new unified API introduces comprehensive support for node groups, allowing visual organization of related nodes:
+
+#### Group Operations
+
+```python
+# Create a group
+group_info = api.create_node_group(
+    name="Processing",           # Unique group name
+    members=["nodeA", "nodeB"],  # List of node names to include
+    color=(65, 105, 225, 80)     # Optional RGBA color tuple
+)  # Returns: dict with group info
+
+# Delete a group (nodes are preserved)
+success = api.delete_node_group("Processing")  # Returns: bool
+
+# Rename a group
+success = api.rename_node_group("Processing", "Data Processing")  # Returns: bool
+
+# Add nodes to an existing group
+success = api.add_to_node_group("Processing", ["nodeC", "nodeD"])  # Returns: bool
+
+# Remove nodes from a group
+success = api.remove_from_node_group("Processing", ["nodeA"])  # Returns: bool
+
+# Validate a group (check for missing nodes, etc.)
+issues = api.validate_node_group("Processing")  # Returns: list[str]
+
+# List all groups
+groups = api.list_node_groups()  # Returns: list[str]
+```
+
+#### Additional Group Helpers
+
+```python
+# Get members of a group
+members = api.get_group_members("Processing")  # Returns: list[str]
+
+# Check which group contains a node
+group_name = api.get_node_group("nodeA")  # Returns: str or None
+
+# Set group color
+api.set_group_color("Processing", (255, 0, 0, 100))
+
+# Check if group exists
+exists = api.group_exists("Processing")  # Returns: bool
+```
+
+#### Group Error Handling
+
+```python
+from nodz.controllers import (
+    NodeGroupError,          # Base group exception
+    GroupNotFoundError,      # Group doesn't exist
+    GroupExistsError,        # Group already exists
+    NodeAlreadyInGroupError, # Node is already in another group
+)
+
+try:
+    api.create_node_group("MyGroup", ["nodeA"])
+except GroupExistsError as e:
+    print(f"Group '{e.group_name}' already exists")
+except NodeAlreadyInGroupError as e:
+    print(f"Node '{e.node_name}' is already in '{e.existing_group}'")
+```
+
+#### Keyboard Shortcut
+
+- **Ctrl+G**: Create a group from currently selected nodes
+
+### 2. Enhanced Error Handling
 
 The new API provides comprehensive error handling with custom exceptions:
 
@@ -393,7 +464,7 @@ except ConnectionError as e:
     print(f"Connection error: {e}")
 ```
 
-### 2. Graph Analysis Tools
+### 3. Graph Analysis Tools
 
 ```python
 # Get graph statistics
@@ -417,7 +488,7 @@ upstream = api.get_upstream_nodes('myNode')
 downstream = api.get_downstream_nodes('myNode')
 ```
 
-### 3. Validation Tools
+### 4. Validation Tools
 
 ```python
 # Validate graph integrity
@@ -429,7 +500,7 @@ else:
     print("Graph is valid")
 ```
 
-### 4. Utility Methods
+### 5. Utility Methods
 
 ```python
 # Check existence
@@ -449,23 +520,23 @@ connections = api.get_connections()
 node_connections = api.get_node_connections('myNode')
 ```
 
-### 5. Position Management
+### 6. Position Management
 
 ```python
 # Get and set node positions
 position = api.get_node_position('myNode')
 api.set_node_position('myNode', QtCore.QPointF(200, 150))
 ```
 
-### 6. Logging Control
+### 7. Logging Control
 
 ```python
 # Control logging levels
 api.set_logging_level('DEBUG')
 current_level = api.get_logging_level()
 ```
 
-### 7. Viewport Control
+### 8. Viewport Control
 
 ```python
 # Save and restore viewport state
@@ -596,7 +667,7 @@ nodz.api.signals.node_created.connect(callback)
 - [ ] Add error handling with new exception types
 - [ ] Test all functionality with the new API
 - [ ] Update documentation and comments
-- [ ] Consider using new features (graph analysis, validation, etc.)
+- [ ] Consider using new features (graph analysis, validation, node groups, etc.)
 
 ---
 

README.md

@@ -181,6 +181,8 @@ L             : Auto-layout graph hierarchically
 S (hold)      : Snap selected nodes to grid
 H             : Toggle help overlay
 Alt+Drag      : Cut connections with line
+Ctrl+G        : Create group from selected nodes
+Ctrl+Shift+G  : Remove selected groups
 ```
 
 ### Advanced Features
@@ -191,6 +193,53 @@ Alt+Drag      : Cut connections with line
 - **Undo/Redo Ready**: Architecture supports command pattern implementation
 - **Plugin System**: Extensible preset system for custom node types
 
+### Node Groups
+
+Node groups allow you to visually organize related nodes within colored, labeled containers. Groups help manage complex graphs by providing logical grouping and collective manipulation of nodes.
+
+**Visual Representation:**
+- Semi-transparent colored background box
+- Title label displayed at the top of the group
+- Automatically resizes to encompass all member nodes
+- Groups are rendered behind nodes to keep nodes as primary interactive elements
+
+**Creating Groups:**
+- Select one or more nodes
+- Press `Ctrl+G` to create a group from the selection
+- Groups are automatically named and colored (customizable via API)
+
+**Behavior:**
+- Moving a group moves all member nodes together
+- A node can only belong to one group at a time
+- Deleting a group preserves the member nodes
+- When a grouped node is deleted, it is automatically removed from its group
+
+**Example Usage:**
+
+```python
+# Create nodes
+api.create_node("Input", position=QtCore.QPointF(100, 100))
+api.create_node("Process", position=QtCore.QPointF(300, 100))
+api.create_node("Output", position=QtCore.QPointF(500, 100))
+
+# Group related nodes
+api.create_node_group("Processing Pipeline", ["Input", "Process"])
+
+# Add another node to existing group
+api.add_to_node_group("Processing Pipeline", "Output")
+
+# Customize group color (RGBA)
+api.set_group_color("Processing Pipeline", (65, 105, 225, 80))
+
+# List all groups
+groups = api.list_node_groups()
+print(f"Groups: {groups}")
+
+# Get nodes in a group
+members = api.get_group_members("Processing Pipeline")
+print(f"Members: {members}")
+```
+
 ## Unified API Reference
 
 Nodz provides a comprehensive unified API through the `NodzAPI` class that handles all graph operations:
@@ -281,6 +330,31 @@ except ValueError:
     pass
 ```
 
+### Group Operations
+
+```python
+# Create a group from selected nodes
+group_info = api.create_node_group(name, members=None, color=None)  # Returns dict with group info
+
+# Manage groups
+api.delete_node_group(group_name)  # Returns bool
+api.rename_node_group(group_name, new_name)  # Returns bool
+
+# Manage group membership
+api.add_to_node_group(group_name, node_names)  # Returns bool
+api.remove_from_node_group(group_name, node_names)  # Returns bool
+
+# Query groups
+groups = api.list_node_groups()  # Returns list of group names
+issues = api.validate_node_group(group_name)  # Returns list of validation issues
+
+# Additional helpers
+members = api.get_group_members(group_name)  # Get nodes in a group
+group = api.get_node_group(node_name)  # Get group containing a node (or None)
+api.set_group_color(group_name, (r, g, b, a))  # Set group RGBA color
+exists = api.group_exists(group_name)  # Check if group exists
+```
+
 ### Utility Methods
 
 ```python
@@ -307,6 +381,11 @@ from nodz.controllers import (
     AttributeNotFoundError, # Attribute doesn't exist
     ConnectionError,        # Connection-related errors
     IncompatibleTypesError, # Type mismatch in connections
+    # Group-related errors
+    NodeGroupError,         # Base group exception
+    GroupNotFoundError,     # Group doesn't exist
+    GroupExistsError,       # Group already exists
+    NodeAlreadyInGroupError,# Node is already in another group
 )
 
 try:
@@ -317,6 +396,14 @@ except IncompatibleTypesError as e:
     print(f"Type mismatch: {e.source_type} -> {e.target_type}")
 except NodzError as e:
     print(f"General error: {e}")
+
+# Group error handling example
+try:
+    api.create_node_group("MyGroup", ["NodeA", "NodeB"])
+except GroupExistsError as e:
+    print(f"Group already exists: {e.group_name}")
+except NodeAlreadyInGroupError as e:
+    print(f"Node '{e.node_name}' is already in group '{e.existing_group}'")
 ```
 
 ## Examples

nodz/__init__.py

@@ -28,13 +28,13 @@
     ConnectionController,
     GraphController,
     NodzError,
-    NodeError,
-    NodeNotFoundError,
-    NodeExistsError,
-    AttributeError,
-    AttributeNotFoundError,
-    ConnectionError,
-    IncompatibleTypesError,
+    NodzNodeError,
+    NodzNodeNotFoundError,
+    NodzNodeExistsError,
+    NodzAttributeError,
+    NodzAttributeNotFoundError,
+    NodzConnectionError,
+    NodzIncompatibleTypesError,
 )
 
 from .main import NodzView, NodzScene, create_nodz_view
@@ -56,13 +56,13 @@
     "ConnectionController",
     "GraphController",
     "NodzError",
-    "NodeError",
-    "NodeNotFoundError",
-    "NodeExistsError",
-    "AttributeError",
-    "AttributeNotFoundError",
-    "ConnectionError",
-    "IncompatibleTypesError",
+    "NodzNodeError",
+    "NodzNodeNotFoundError",
+    "NodzNodeExistsError",
+    "NodzAttributeError",
+    "NodzAttributeNotFoundError",
+    "NodzConnectionError",
+    "NodzIncompatibleTypesError",
     "NodzView",
     "NodzScene",
     "create_nodz_view",