anatools 6.0.0__py3-none-any.whl → 6.0.1__py3-none-any.whl

{anatools-6.0.0.data → anatools-6.0.1.data}/scripts/renderedai

@@ -37,7 +37,9 @@ import argparse
 import json
 import os
 import sys
-from typing import Any, List
+from typing import Any, Dict, List, Optional
+
+import yaml
 
 
 def get_client():
@@ -104,6 +106,55 @@ def parse_list_arg(value: str) -> List[str]:
     return [item.strip() for item in value.split(',')]
 
 
+def load_graph_file(filepath: str) -> Optional[Dict[str, Any]]:
+    """Load a graph from a YAML or JSON file.
+
+    Args:
+        filepath: Path to the graph file (.yaml, .yml, or .json)
+
+    Returns:
+        Dict containing the graph data, or None if loading failed
+    """
+    if not os.path.exists(filepath):
+        output_error(f"File not found: {filepath}", "FILE_NOT_FOUND")
+        return None
+
+    try:
+        with open(filepath, 'r') as f:
+            if filepath.endswith('.json'):
+                return json.load(f)
+            else:  # .yaml or .yml
+                return yaml.safe_load(f)
+    except (json.JSONDecodeError, yaml.YAMLError) as e:
+        output_error(f"Failed to parse file: {str(e)}", "PARSE_ERROR")
+        return None
+    except Exception as e:
+        output_error(f"Failed to read file: {str(e)}", "READ_ERROR")
+        return None
+
+
+def save_graph_file(filepath: str, data: Dict[str, Any]) -> bool:
+    """Save a graph to a YAML or JSON file.
+
+    Args:
+        filepath: Path to save the graph file (.yaml, .yml, or .json)
+        data: Graph data to save
+
+    Returns:
+        True if save succeeded, False otherwise
+    """
+    try:
+        with open(filepath, 'w') as f:
+            if filepath.endswith('.json'):
+                json.dump(data, f, indent=2)
+            else:  # .yaml or .yml
+                yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+        return True
+    except Exception as e:
+        output_error(f"Failed to save file: {str(e)}", "WRITE_ERROR")
+        return False
+
+
 # =============================================================================
 # WORKSPACES
 # =============================================================================
@@ -277,16 +328,25 @@ def cmd_datasets_cancel(args):
 
 
 def cmd_datasets_download(args):
-    """Download a dataset."""
+    """Download a dataset or a single file from a dataset."""
     client = get_client()
     workspace_id = require_arg(args, 'workspaceid', 'Workspace ID')
     dataset_id = require_arg(args, 'datasetid', 'Dataset ID')
 
-    result = client.download_dataset(
-        workspaceId=workspace_id,
-        datasetId=dataset_id,
-        localDir=args.outputdir
-    )
+    # If filepath is provided, download a single file; otherwise download the entire dataset
+    if args.filepath:
+        result = client.download_dataset_file(
+            workspaceId=workspace_id,
+            datasetId=dataset_id,
+            filepath=args.filepath,
+            localDir=args.outputdir
+        )
+    else:
+        result = client.download_dataset(
+            workspaceId=workspace_id,
+            datasetId=dataset_id,
+            localDir=args.outputdir
+        )
     output_json({"downloadPath": result})
 
 
@@ -1089,6 +1149,847 @@ def cmd_graph_editor_open(args):
     })
 
 
+def cmd_graph_editor_edit_node(args):
+    """Edit a node's values in a local graph file.
+
+    Modifies the values of an existing node in the graph. Use --values to pass
+    a JSON object with the key-value pairs to update. Existing values not
+    specified in --values are preserved.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    node_name = require_arg(args, 'node', 'Node name')
+    values_json = require_arg(args, 'values', 'Values JSON')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+    if node_name not in nodes:
+        output_error(f"Node '{node_name}' not found in graph", "NODE_NOT_FOUND")
+        return
+
+    # Parse the values JSON
+    try:
+        new_values = json.loads(values_json)
+    except json.JSONDecodeError as e:
+        output_error(f"Invalid JSON for --values: {str(e)}", "INVALID_JSON")
+        return
+
+    if not isinstance(new_values, dict):
+        output_error("--values must be a JSON object", "INVALID_VALUES")
+        return
+
+    # Update the node's values
+    node = nodes[node_name]
+    if 'values' not in node:
+        node['values'] = {}
+
+    node['values'].update(new_values)
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "node": node_name,
+        "updatedValues": new_values,
+        "allValues": node['values']
+    })
+
+
+def cmd_graph_editor_add_node(args):
+    """Add a new node to a local graph file.
+
+    Adds a node with the specified nodeClass. Use --name for a custom node name
+    (defaults to nodeClass_N where N is auto-incremented). Use --values to set
+    initial parameter values, --location to set x,y position.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    node_class = require_arg(args, 'nodeclass', 'Node class')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    # Generate node name if not provided
+    node_name = args.name
+    if not node_name:
+        # Find the next available number for this node class
+        counter = 1
+        while f"{node_class}_{counter}" in nodes:
+            counter += 1
+        node_name = f"{node_class}_{counter}"
+
+    if node_name in nodes:
+        output_error(f"Node '{node_name}' already exists in graph", "NODE_EXISTS")
+        return
+
+    # Parse optional values
+    values = {}
+    if args.values:
+        try:
+            values = json.loads(args.values)
+            if not isinstance(values, dict):
+                output_error("--values must be a JSON object", "INVALID_VALUES")
+                return
+        except json.JSONDecodeError as e:
+            output_error(f"Invalid JSON for --values: {str(e)}", "INVALID_JSON")
+            return
+
+    # Parse optional location
+    location = {"x": 0, "y": 0}
+    if args.location:
+        try:
+            loc = json.loads(args.location)
+            if isinstance(loc, dict) and 'x' in loc and 'y' in loc:
+                location = {"x": loc['x'], "y": loc['y']}
+            elif isinstance(loc, list) and len(loc) >= 2:
+                location = {"x": loc[0], "y": loc[1]}
+            else:
+                output_error("--location must be {\"x\": N, \"y\": N} or [x, y]", "INVALID_LOCATION")
+                return
+        except json.JSONDecodeError as e:
+            output_error(f"Invalid JSON for --location: {str(e)}", "INVALID_JSON")
+            return
+
+    # Create the new node
+    new_node = {
+        "name": node_name,
+        "nodeClass": node_class,
+        "color": args.color or "#808080",
+        "links": {},
+        "location": location,
+        "ports": {
+            "inputs": [],
+            "outputs": []
+        },
+        "values": values
+    }
+
+    if args.tooltip:
+        new_node["tooltip"] = args.tooltip
+
+    nodes[node_name] = new_node
+    graph['nodes'] = nodes
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "node": node_name,
+        "nodeClass": node_class,
+        "location": location,
+        "values": values
+    })
+
+
+def cmd_graph_editor_add_link(args):
+    """Add a link between two nodes in a local graph file.
+
+    Creates a connection from a source node's output port to a target node's
+    input port. The link is stored on the target node under its links property.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    source_node = require_arg(args, 'source', 'Source node name')
+    output_port = require_arg(args, 'output', 'Output port name')
+    target_node = require_arg(args, 'target', 'Target node name')
+    input_port = require_arg(args, 'input', 'Input port name')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    # Validate source node exists
+    if source_node not in nodes:
+        output_error(f"Source node '{source_node}' not found in graph", "SOURCE_NOT_FOUND")
+        return
+
+    # Validate target node exists
+    if target_node not in nodes:
+        output_error(f"Target node '{target_node}' not found in graph", "TARGET_NOT_FOUND")
+        return
+
+    target = nodes[target_node]
+
+    # Initialize links if not present
+    if 'links' not in target:
+        target['links'] = {}
+
+    # Add or append to the input port's links
+    if input_port not in target['links']:
+        target['links'][input_port] = []
+
+    # Check if this exact link already exists
+    new_link = {
+        "outputPort": output_port,
+        "sourceNode": source_node
+    }
+
+    for existing_link in target['links'][input_port]:
+        if (existing_link.get('outputPort') == output_port and
+                existing_link.get('sourceNode') == source_node):
+            output_error(
+                f"Link already exists: {source_node}.{output_port} -> {target_node}.{input_port}",
+                "LINK_EXISTS"
+            )
+            return
+
+    target['links'][input_port].append(new_link)
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "link": {
+            "source": source_node,
+            "outputPort": output_port,
+            "target": target_node,
+            "inputPort": input_port
+        }
+    })
+
+
+def cmd_graph_editor_remove_node(args):
+    """Remove a node from a local graph file.
+
+    Removes the specified node and all links connected to it (both incoming
+    links on this node and outgoing links from other nodes that reference it).
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    node_name = require_arg(args, 'node', 'Node name')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    if node_name not in nodes:
+        output_error(f"Node '{node_name}' not found in graph", "NODE_NOT_FOUND")
+        return
+
+    # Remove the node
+    removed_node = nodes.pop(node_name)
+
+    # Remove all links that reference this node from other nodes
+    removed_links = []
+    for other_name, other_node in nodes.items():
+        links = other_node.get('links', {})
+        for port_name, port_links in list(links.items()):
+            original_count = len(port_links)
+            port_links[:] = [
+                link for link in port_links
+                if link.get('sourceNode') != node_name
+            ]
+            if len(port_links) < original_count:
+                removed_links.append({
+                    "target": other_name,
+                    "inputPort": port_name,
+                    "source": node_name
+                })
+            # Clean up empty link lists
+            if not port_links:
+                del links[port_name]
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "removedNode": node_name,
+        "nodeClass": removed_node.get('nodeClass'),
+        "removedLinks": removed_links
+    })
+
+
+def cmd_graph_editor_remove_link(args):
+    """Remove a link between two nodes in a local graph file.
+
+    Removes the connection from the source node's output port to the target
+    node's input port.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    source_node = require_arg(args, 'source', 'Source node name')
+    output_port = require_arg(args, 'output', 'Output port name')
+    target_node = require_arg(args, 'target', 'Target node name')
+    input_port = require_arg(args, 'input', 'Input port name')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    # Validate target node exists
+    if target_node not in nodes:
+        output_error(f"Target node '{target_node}' not found in graph", "TARGET_NOT_FOUND")
+        return
+
+    target = nodes[target_node]
+    links = target.get('links', {})
+
+    if input_port not in links:
+        output_error(
+            f"No links found on input port '{input_port}' of node '{target_node}'",
+            "LINK_NOT_FOUND"
+        )
+        return
+
+    # Find and remove the specific link
+    port_links = links[input_port]
+    original_count = len(port_links)
+
+    port_links[:] = [
+        link for link in port_links
+        if not (link.get('outputPort') == output_port and
+                link.get('sourceNode') == source_node)
+    ]
+
+    if len(port_links) == original_count:
+        output_error(
+            f"Link not found: {source_node}.{output_port} -> {target_node}.{input_port}",
+            "LINK_NOT_FOUND"
+        )
+        return
+
+    # Clean up empty link lists
+    if not port_links:
+        del links[input_port]
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "removedLink": {
+            "source": source_node,
+            "outputPort": output_port,
+            "target": target_node,
+            "inputPort": input_port
+        }
+    })
+
+
+def cmd_graph_editor_add_volume_file(args):
+    """Add a VolumeFile node to a local graph file.
+
+    Creates a VolumeFile node that references a file in a Rendered.ai volume.
+    The volume reference uses the format volumeId:/path/to/file.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    volume_id = require_arg(args, 'volumeid', 'Volume ID')
+    volume_path = require_arg(args, 'path', 'File path in volume')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    # Generate node name if not provided
+    node_name = args.name
+    if not node_name:
+        counter = 1
+        while f"VolumeFile_{counter}" in nodes:
+            counter += 1
+        node_name = f"VolumeFile_{counter}"
+
+    if node_name in nodes:
+        output_error(f"Node '{node_name}' already exists in graph", "NODE_EXISTS")
+        return
+
+    # Parse optional location
+    location = {"x": 0, "y": 0}
+    if args.location:
+        try:
+            loc = json.loads(args.location)
+            if isinstance(loc, dict) and 'x' in loc and 'y' in loc:
+                location = {"x": loc['x'], "y": loc['y']}
+            elif isinstance(loc, list) and len(loc) >= 2:
+                location = {"x": loc[0], "y": loc[1]}
+            else:
+                output_error("--location must be {\"x\": N, \"y\": N} or [x, y]", "INVALID_LOCATION")
+                return
+        except json.JSONDecodeError as e:
+            output_error(f"Invalid JSON for --location: {str(e)}", "INVALID_JSON")
+            return
+
+    # Normalize path (ensure it starts with /)
+    if not volume_path.startswith('/'):
+        volume_path = '/' + volume_path
+
+    # Build the volume reference
+    volume_ref = f"{volume_id}:{volume_path}"
+
+    # Build tooltip (use volume name if provided, otherwise volume ID)
+    volume_display = args.volumename or volume_id
+    tooltip = f"{volume_display}:{volume_path}"
+
+    # Create the VolumeFile node
+    new_node = {
+        "name": node_name,
+        "nodeClass": "VolumeFile",
+        "color": "#246BB3",
+        "hash": "8d56c9b8e4bae85fd61620e1d4d44a24",
+        "links": {},
+        "location": location,
+        "ports": {
+            "inputs": [
+                {
+                    "name": "File",
+                    "description": "",
+                    "default": volume_ref,
+                    "hidden": True
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "File",
+                    "description": ""
+                }
+            ]
+        },
+        "tooltip": tooltip,
+        "values": {
+            "File": volume_ref
+        }
+    }
+
+    nodes[node_name] = new_node
+    graph['nodes'] = nodes
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "node": node_name,
+        "nodeClass": "VolumeFile",
+        "volumeId": volume_id,
+        "path": volume_path,
+        "volumeRef": volume_ref,
+        "location": location
+    })
+
+
+def cmd_graph_editor_add_volume_directory(args):
+    """Add a VolumeDirectory node to a local graph file.
+
+    Creates a VolumeDirectory node that references a directory in a Rendered.ai volume.
+    The volume reference uses the format volumeId:/path/to/directory.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    volume_id = require_arg(args, 'volumeid', 'Volume ID')
+    volume_path = args.path or '/'
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    # Generate node name if not provided
+    node_name = args.name
+    if not node_name:
+        counter = 1
+        while f"VolumeDirectory_{counter}" in nodes:
+            counter += 1
+        node_name = f"VolumeDirectory_{counter}"
+
+    if node_name in nodes:
+        output_error(f"Node '{node_name}' already exists in graph", "NODE_EXISTS")
+        return
+
+    # Parse optional location
+    location = {"x": 0, "y": 0}
+    if args.location:
+        try:
+            loc = json.loads(args.location)
+            if isinstance(loc, dict) and 'x' in loc and 'y' in loc:
+                location = {"x": loc['x'], "y": loc['y']}
+            elif isinstance(loc, list) and len(loc) >= 2:
+                location = {"x": loc[0], "y": loc[1]}
+            else:
+                output_error("--location must be {\"x\": N, \"y\": N} or [x, y]", "INVALID_LOCATION")
+                return
+        except json.JSONDecodeError as e:
+            output_error(f"Invalid JSON for --location: {str(e)}", "INVALID_JSON")
+            return
+
+    # Normalize path (ensure it starts with /)
+    if not volume_path.startswith('/'):
+        volume_path = '/' + volume_path
+
+    # Build the volume reference
+    volume_ref = f"{volume_id}:{volume_path}"
+
+    # Build tooltip (use volume name if provided, otherwise volume ID)
+    volume_display = args.volumename or volume_id
+    tooltip = f"{volume_display}:{volume_path}"
+
+    # Create the VolumeDirectory node
+    new_node = {
+        "name": node_name,
+        "nodeClass": "VolumeDirectory",
+        "color": "#246BB3",
+        "hash": "a7c19eb160150ee04d82af60c9332d104f0a7f89",
+        "links": {},
+        "location": location,
+        "ports": {
+            "inputs": [
+                {
+                    "name": "Directory",
+                    "description": "",
+                    "default": volume_ref,
+                    "hidden": True
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "Directory",
+                    "description": ""
+                }
+            ]
+        },
+        "tooltip": tooltip,
+        "values": {
+            "Directory": volume_ref
+        }
+    }
+
+    nodes[node_name] = new_node
+    graph['nodes'] = nodes
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "node": node_name,
+        "nodeClass": "VolumeDirectory",
+        "volumeId": volume_id,
+        "path": volume_path,
+        "volumeRef": volume_ref,
+        "location": location
+    })
+
+
+def cmd_graph_editor_list_nodes(args):
+    """List all nodes in a local graph file.
+
+    Returns a summary of all nodes including their name, class, location,
+    and connection counts. Useful for understanding graph structure.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    # Build summary for each node
+    node_list = []
+    for node_name, node_data in nodes.items():
+        # Count incoming links
+        incoming_links = 0
+        link_sources = []
+        for port_name, port_links in node_data.get('links', {}).items():
+            incoming_links += len(port_links)
+            for link in port_links:
+                link_sources.append(f"{link.get('sourceNode')}.{link.get('outputPort')}")
+
+        # Count outgoing links (links from other nodes to this one)
+        outgoing_links = 0
+        link_targets = []
+        for other_name, other_data in nodes.items():
+            if other_name == node_name:
+                continue
+            for port_name, port_links in other_data.get('links', {}).items():
+                for link in port_links:
+                    if link.get('sourceNode') == node_name:
+                        outgoing_links += 1
+                        link_targets.append(f"{other_name}.{port_name}")
+
+        node_summary = {
+            "name": node_name,
+            "nodeClass": node_data.get('nodeClass'),
+            "location": node_data.get('location'),
+            "incomingLinks": incoming_links,
+            "outgoingLinks": outgoing_links,
+            "hasValues": bool(node_data.get('values'))
+        }
+
+        if args.verbose:
+            node_summary["linkSources"] = link_sources
+            node_summary["linkTargets"] = link_targets
+
+        node_list.append(node_summary)
+
+    # Sort by name for consistent output
+    node_list.sort(key=lambda x: x['name'])
+
+    output_json({
+        "file": os.path.abspath(filepath),
+        "nodeCount": len(node_list),
+        "nodes": node_list
+    })
+
+
+def cmd_graph_editor_get_node(args):
+    """Get detailed information about a specific node in a local graph file.
+
+    Returns full node data including all values, ports, links, and metadata.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    node_name = require_arg(args, 'node', 'Node name')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    if node_name not in nodes:
+        output_error(f"Node '{node_name}' not found in graph", "NODE_NOT_FOUND")
+        return
+
+    node_data = nodes[node_name]
+
+    # Find outgoing links (other nodes that link to this one)
+    outgoing_links = []
+    for other_name, other_data in nodes.items():
+        if other_name == node_name:
+            continue
+        for port_name, port_links in other_data.get('links', {}).items():
+            for link in port_links:
+                if link.get('sourceNode') == node_name:
+                    outgoing_links.append({
+                        "targetNode": other_name,
+                        "targetPort": port_name,
+                        "outputPort": link.get('outputPort')
+                    })
+
+    output_json({
+        "file": os.path.abspath(filepath),
+        "node": node_name,
+        "nodeClass": node_data.get('nodeClass'),
+        "color": node_data.get('color'),
+        "location": node_data.get('location'),
+        "tooltip": node_data.get('tooltip'),
+        "hash": node_data.get('hash'),
+        "values": node_data.get('values', {}),
+        "ports": node_data.get('ports', {}),
+        "incomingLinks": node_data.get('links', {}),
+        "outgoingLinks": outgoing_links
+    })
+
+
+def cmd_graph_editor_move_node(args):
+    """Move a node to a new location in a local graph file.
+
+    Updates the node's x,y coordinates for visual positioning in the graph editor.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    node_name = require_arg(args, 'node', 'Node name')
+    location_str = require_arg(args, 'location', 'Location')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    if node_name not in nodes:
+        output_error(f"Node '{node_name}' not found in graph", "NODE_NOT_FOUND")
+        return
+
+    # Parse location
+    try:
+        loc = json.loads(location_str)
+        if isinstance(loc, dict) and 'x' in loc and 'y' in loc:
+            location = {"x": loc['x'], "y": loc['y']}
+        elif isinstance(loc, list) and len(loc) >= 2:
+            location = {"x": loc[0], "y": loc[1]}
+        else:
+            output_error("--location must be {\"x\": N, \"y\": N} or [x, y]", "INVALID_LOCATION")
+            return
+    except json.JSONDecodeError as e:
+        output_error(f"Invalid JSON for --location: {str(e)}", "INVALID_JSON")
+        return
+
+    old_location = nodes[node_name].get('location', {})
+    nodes[node_name]['location'] = location
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "node": node_name,
+        "oldLocation": old_location,
+        "newLocation": location
+    })
+
+
+def cmd_graph_editor_clone_node(args):
+    """Clone an existing node in a local graph file.
+
+    Creates a copy of a node with a new name. The cloned node has the same
+    nodeClass, values, ports, and color, but no links (links must be added
+    separately). The location is offset slightly from the original.
+    """
+    filepath = require_arg(args, 'file', 'Graph file path')
+    source_node = require_arg(args, 'source', 'Source node name')
+
+    graph = load_graph_file(filepath)
+    if graph is None:
+        return
+
+    nodes = graph.get('nodes', {})
+
+    if source_node not in nodes:
+        output_error(f"Source node '{source_node}' not found in graph", "NODE_NOT_FOUND")
+        return
+
+    source_data = nodes[source_node]
+    node_class = source_data.get('nodeClass', 'Unknown')
+
+    # Generate new node name if not provided
+    new_name = args.name
+    if not new_name:
+        counter = 1
+        while f"{node_class}_{counter}" in nodes:
+            counter += 1
+        new_name = f"{node_class}_{counter}"
+
+    if new_name in nodes:
+        output_error(f"Node '{new_name}' already exists in graph", "NODE_EXISTS")
+        return
+
+    # Parse optional location, or offset from source
+    if args.location:
+        try:
+            loc = json.loads(args.location)
+            if isinstance(loc, dict) and 'x' in loc and 'y' in loc:
+                location = {"x": loc['x'], "y": loc['y']}
+            elif isinstance(loc, list) and len(loc) >= 2:
+                location = {"x": loc[0], "y": loc[1]}
+            else:
+                output_error("--location must be {\"x\": N, \"y\": N} or [x, y]", "INVALID_LOCATION")
+                return
+        except json.JSONDecodeError as e:
+            output_error(f"Invalid JSON for --location: {str(e)}", "INVALID_JSON")
+            return
+    else:
+        # Offset from source location
+        source_loc = source_data.get('location', {"x": 0, "y": 0})
+        location = {
+            "x": source_loc.get('x', 0) + 50,
+            "y": source_loc.get('y', 0) + 50
+        }
+
+    # Create the cloned node (deep copy values and ports, but not links)
+    import copy
+    cloned_node = {
+        "name": new_name,
+        "nodeClass": node_class,
+        "color": source_data.get('color', '#808080'),
+        "hash": source_data.get('hash'),
+        "links": {},  # No links for cloned node
+        "location": location,
+        "ports": copy.deepcopy(source_data.get('ports', {"inputs": [], "outputs": []})),
+        "values": copy.deepcopy(source_data.get('values', {}))
+    }
+
+    if source_data.get('tooltip'):
+        cloned_node['tooltip'] = source_data['tooltip']
+
+    nodes[new_name] = cloned_node
+    graph['nodes'] = nodes
+
+    if not save_graph_file(filepath, graph):
+        return
+
+    output_json({
+        "success": True,
+        "file": os.path.abspath(filepath),
+        "sourceNode": source_node,
+        "clonedNode": new_name,
+        "nodeClass": node_class,
+        "location": location
+    })
+
+
+def cmd_graph_editor_status(args):
+    """Get the status and validation errors from the graph editor.
+
+    Reads the graph editor status file to check for validation errors in
+    open editor sessions. Returns session info including any errors.
+    """
+    status_path = os.path.join(os.path.expanduser('~'), '.theia', 'graph-editor-status.json')
+
+    if not os.path.exists(status_path):
+        output_json({
+            "status": "no_status_file",
+            "message": "No graph editor status file found. The graph editor may not have been opened yet.",
+            "statusPath": status_path,
+            "sessions": []
+        })
+        return
+
+    try:
+        with open(status_path, 'r') as f:
+            status_data = json.load(f)
+    except json.JSONDecodeError as e:
+        output_error(f"Failed to parse status file: {str(e)}", "PARSE_ERROR")
+        return
+    except Exception as e:
+        output_error(f"Failed to read status file: {str(e)}", "READ_ERROR")
+        return
+
+    sessions = status_data.get('sessions', [])
+
+    # If a specific graph file is requested, filter to that session
+    if args.file:
+        target_path = os.path.abspath(args.file)
+        sessions = [s for s in sessions if s.get('graphPath') == target_path]
+
+    # Build response with error summary
+    total_errors = 0
+    sessions_with_errors = 0
+    for session in sessions:
+        errors = session.get('errors', [])
+        if errors:
+            sessions_with_errors += 1
+            total_errors += len(errors)
+
+    output_json({
+        "status": "ok",
+        "statusPath": status_path,
+        "lastUpdated": status_data.get('lastUpdated'),
+        "sessionCount": len(sessions),
+        "sessionsWithErrors": sessions_with_errors,
+        "totalErrors": total_errors,
+        "sessions": sessions
+    })
+
+
 # =============================================================================
 # CHANNELS
 # =============================================================================
@@ -1116,7 +2017,62 @@ def cmd_channels_schema(args):
         channelId=channel_id,
         fields=parse_list_arg(args.fields) if args.fields else None
     )
-    output_json(result)
+
+    # Apply filters if specified
+    if args.category or args.subcategory or args.search:
+        filtered = []
+        search_term = args.search.lower() if args.search else None
+
+        for node in result:
+            # Filter by category
+            if args.category and node.get('category', '').lower() != args.category.lower():
+                continue
+
+            # Filter by subcategory
+            if args.subcategory and node.get('subcategory', '').lower() != args.subcategory.lower():
+                continue
+
+            # Search across multiple fields
+            if search_term:
+                searchable_fields = [
+                    node.get('name', ''),
+                    node.get('category', ''),
+                    node.get('subcategory', ''),
+                    node.get('tooltip', ''),
+                    node.get('description', ''),
+                ]
+                # Also search in input/output names and descriptions
+                for inp in node.get('inputs', []):
+                    searchable_fields.append(inp.get('name', ''))
+                    searchable_fields.append(inp.get('description', ''))
+                for out in node.get('outputs', []):
+                    searchable_fields.append(out.get('name', ''))
+                    searchable_fields.append(out.get('description', ''))
+
+                combined = ' '.join(str(f) for f in searchable_fields).lower()
+                if search_term not in combined:
+                    continue
+
+            filtered.append(node)
+
+        result = filtered
+
+    # List categories and subcategories if requested
+    if args.list_categories:
+        categories = sorted(set(node.get('category', '') for node in result if node.get('category')))
+        subcategories = sorted(set(node.get('subcategory', '') for node in result if node.get('subcategory')))
+        output_json({
+            "categories": categories,
+            "subcategories": subcategories
+        })
+        return
+
+    # Output names only if requested
+    if args.names_only:
+        names = sorted([node.get('name', '') for node in result])
+        output_json(names)
+    else:
+        output_json(result)
 
 
 def cmd_channels_nodes(args):
@@ -1456,6 +2412,104 @@ def cmd_annotations_edit(args):
     output_json({"success": result})
 
 
+def cmd_annotations_view(args):
+    """Generate an image with annotations overlayed.
+
+    This command draws annotations (bounding boxes, 3D boxes, or segmentation outlines)
+    on an image from a dataset. The image must be part of a dataset directory structure
+    that includes annotations/ and metadata/ folders with ANA-format annotation files.
+    """
+    from anatools.annotations import annotations
+
+    image_path = require_arg(args, 'imagepath', 'Image path')
+    out_dir = require_arg(args, 'outdir', 'Output directory')
+
+    # Parse draw types - can be comma-separated for multiple types
+    draw_types = parse_list_arg(args.drawtype) if args.drawtype else ['box_2d']
+    valid_types = ['box_2d', 'box_3d', 'segmentation']
+    for dt in draw_types:
+        if dt not in valid_types:
+            output_error(f"Invalid draw type '{dt}'. Must be one of: {', '.join(valid_types)}", "INVALID_DRAW_TYPE")
+            sys.exit(1)
+
+    # Parse optional filters
+    object_ids = None
+    object_types = None
+    if args.objectids:
+        try:
+            object_ids = [int(x) for x in parse_list_arg(args.objectids)]
+        except ValueError:
+            output_error("Object IDs must be integers", "INVALID_OBJECT_IDS")
+            sys.exit(1)
+    if args.objecttypes:
+        object_types = parse_list_arg(args.objecttypes)
+
+    # Parse colors if provided (JSON format)
+    colors = None
+    if args.colors:
+        colors = parse_json_arg(args.colors)
+        # Convert color lists to tuples
+        for key in colors:
+            if isinstance(colors[key], list):
+                colors[key] = tuple(colors[key])
+
+    line_thickness = args.thickness if args.thickness else 1
+
+    ann = annotations()
+    output_paths = []
+
+    try:
+        for draw_type in draw_types:
+            output_path = None
+            if draw_type == 'box_2d':
+                output_path = ann.bounding_box_2d(
+                    image_path=image_path,
+                    out_dir=out_dir,
+                    object_ids=object_ids,
+                    object_types=object_types,
+                    line_thickness=line_thickness,
+                    colors=colors,
+                    quiet=True
+                )
+            elif draw_type == 'box_3d':
+                output_path = ann.bounding_box_3d(
+                    image_path=image_path,
+                    out_dir=out_dir,
+                    object_ids=object_ids,
+                    object_types=object_types,
+                    line_thickness=line_thickness,
+                    colors=colors,
+                    quiet=True
+                )
+            elif draw_type == 'segmentation':
+                output_path = ann.segmentation(
+                    image_path=image_path,
+                    out_dir=out_dir,
+                    object_ids=object_ids,
+                    object_types=object_types,
+                    line_thickness=line_thickness,
+                    colors=colors,
+                    quiet=True
+                )
+
+            if output_path is None:
+                output_error(f"Failed to generate annotated image for draw type '{draw_type}'", "ANNOTATION_ERROR")
+                sys.exit(1)
+            output_paths.append(output_path)
+
+        output_json({
+            "success": True,
+            "outputPaths": output_paths,
+            "drawTypes": draw_types
+        })
+    except FileNotFoundError as e:
+        output_error(f"File not found: {str(e)}", "FILE_NOT_FOUND")
+        sys.exit(1)
+    except Exception as e:
+        output_error(f"Failed to generate annotated image: {str(e)}", "ANNOTATION_ERROR")
+        sys.exit(1)
+
+
 # =============================================================================
 # ANNOTATION-MAPS
 # =============================================================================
@@ -2171,9 +3225,10 @@ Examples:
     ds_cancel.set_defaults(func=cmd_datasets_cancel)
 
     # datasets download
-    ds_download = datasets_sub.add_parser('download', help='Download a dataset')
+    ds_download = datasets_sub.add_parser('download', help='Download a dataset or a single file from a dataset')
     ds_download.add_argument('--workspaceid', required=True, help='Workspace ID')
     ds_download.add_argument('--datasetid', required=True, help='Dataset ID')
+    ds_download.add_argument('--filepath', help='Relative path to a specific file within the dataset (e.g., "images/000000-1-image.png"). If not provided, downloads the entire dataset.')
     ds_download.add_argument('--outputdir', help='Output directory')
     ds_download.set_defaults(func=cmd_datasets_download)
 
@@ -2395,6 +3450,100 @@ Examples:
     ge_open.add_argument('--outputdir', help='Output directory (default: current directory)')
     ge_open.set_defaults(func=cmd_graph_editor_open)
 
+    # graph-editor edit-node
+    ge_edit_node = graph_editor_sub.add_parser('edit-node', help='Edit a node\'s values in a local graph file')
+    ge_edit_node.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_edit_node.add_argument('--node', required=True, help='Name of the node to edit')
+    ge_edit_node.add_argument('--values', required=True, help='JSON object with values to update (e.g., \'{"param": "value"}\')')
+    ge_edit_node.set_defaults(func=cmd_graph_editor_edit_node)
+
+    # graph-editor add-node
+    ge_add_node = graph_editor_sub.add_parser('add-node', help='Add a new node to a local graph file')
+    ge_add_node.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_add_node.add_argument('--nodeclass', required=True, help='Node class to instantiate')
+    ge_add_node.add_argument('--name', help='Custom node name (default: nodeClass_N)')
+    ge_add_node.add_argument('--values', help='JSON object with initial values')
+    ge_add_node.add_argument('--location', help='Position as {"x": N, "y": N} or [x, y]')
+    ge_add_node.add_argument('--color', help='Node color as hex (default: #808080)')
+    ge_add_node.add_argument('--tooltip', help='Node tooltip/description')
+    ge_add_node.set_defaults(func=cmd_graph_editor_add_node)
+
+    # graph-editor add-link
+    ge_add_link = graph_editor_sub.add_parser('add-link', help='Add a link between two nodes')
+    ge_add_link.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_add_link.add_argument('--source', required=True, help='Source node name')
+    ge_add_link.add_argument('--output', required=True, help='Output port name on source node')
+    ge_add_link.add_argument('--target', required=True, help='Target node name')
+    ge_add_link.add_argument('--input', required=True, help='Input port name on target node')
+    ge_add_link.set_defaults(func=cmd_graph_editor_add_link)
+
+    # graph-editor remove-node
+    ge_remove_node = graph_editor_sub.add_parser('remove-node', help='Remove a node and its links from a graph')
+    ge_remove_node.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_remove_node.add_argument('--node', required=True, help='Name of the node to remove')
+    ge_remove_node.set_defaults(func=cmd_graph_editor_remove_node)
+
+    # graph-editor remove-link
+    ge_remove_link = graph_editor_sub.add_parser('remove-link', help='Remove a link between two nodes')
+    ge_remove_link.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_remove_link.add_argument('--source', required=True, help='Source node name')
+    ge_remove_link.add_argument('--output', required=True, help='Output port name on source node')
+    ge_remove_link.add_argument('--target', required=True, help='Target node name')
+    ge_remove_link.add_argument('--input', required=True, help='Input port name on target node')
+    ge_remove_link.set_defaults(func=cmd_graph_editor_remove_link)
+
+    # graph-editor add-volume-file
+    ge_add_vol_file = graph_editor_sub.add_parser('add-volume-file', help='Add a VolumeFile node referencing a file in a volume')
+    ge_add_vol_file.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_add_vol_file.add_argument('--volumeid', required=True, help='Volume UUID')
+    ge_add_vol_file.add_argument('--path', required=True, help='File path within the volume (e.g., /models/model.blend)')
+    ge_add_vol_file.add_argument('--name', help='Custom node name (default: VolumeFile_N)')
+    ge_add_vol_file.add_argument('--volumename', help='Volume display name for tooltip (default: uses volumeid)')
+    ge_add_vol_file.add_argument('--location', help='Position as {"x": N, "y": N} or [x, y]')
+    ge_add_vol_file.set_defaults(func=cmd_graph_editor_add_volume_file)
+
+    # graph-editor add-volume-directory
+    ge_add_vol_dir = graph_editor_sub.add_parser('add-volume-directory', help='Add a VolumeDirectory node referencing a directory in a volume')
+    ge_add_vol_dir.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_add_vol_dir.add_argument('--volumeid', required=True, help='Volume UUID')
+    ge_add_vol_dir.add_argument('--path', help='Directory path within the volume (default: /)')
+    ge_add_vol_dir.add_argument('--name', help='Custom node name (default: VolumeDirectory_N)')
+    ge_add_vol_dir.add_argument('--volumename', help='Volume display name for tooltip (default: uses volumeid)')
+    ge_add_vol_dir.add_argument('--location', help='Position as {"x": N, "y": N} or [x, y]')
+    ge_add_vol_dir.set_defaults(func=cmd_graph_editor_add_volume_directory)
+
+    # graph-editor list-nodes
+    ge_list_nodes = graph_editor_sub.add_parser('list-nodes', help='List all nodes in a local graph file')
+    ge_list_nodes.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_list_nodes.add_argument('--verbose', '-v', action='store_true', help='Include link details')
+    ge_list_nodes.set_defaults(func=cmd_graph_editor_list_nodes)
+
+    # graph-editor get-node
+    ge_get_node = graph_editor_sub.add_parser('get-node', help='Get detailed info about a specific node')
+    ge_get_node.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_get_node.add_argument('--node', required=True, help='Name of the node to inspect')
+    ge_get_node.set_defaults(func=cmd_graph_editor_get_node)
+
+    # graph-editor move-node
+    ge_move_node = graph_editor_sub.add_parser('move-node', help='Move a node to a new location')
+    ge_move_node.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_move_node.add_argument('--node', required=True, help='Name of the node to move')
+    ge_move_node.add_argument('--location', required=True, help='New position as {"x": N, "y": N} or [x, y]')
+    ge_move_node.set_defaults(func=cmd_graph_editor_move_node)
+
+    # graph-editor clone-node
+    ge_clone_node = graph_editor_sub.add_parser('clone-node', help='Clone an existing node')
+    ge_clone_node.add_argument('--file', required=True, help='Path to graph file (.yaml, .yml, or .json)')
+    ge_clone_node.add_argument('--source', required=True, help='Name of the node to clone')
+    ge_clone_node.add_argument('--name', help='Name for the cloned node (default: nodeClass_N)')
+    ge_clone_node.add_argument('--location', help='Position as {"x": N, "y": N} or [x, y] (default: offset from source)')
+    ge_clone_node.set_defaults(func=cmd_graph_editor_clone_node)
+
+    # graph-editor status
+    ge_status = graph_editor_sub.add_parser('status', help='Get graph editor status and validation errors')
+    ge_status.add_argument('--file', help='Filter to a specific graph file path')
+    ge_status.set_defaults(func=cmd_graph_editor_status)
+
     # -------------------------------------------------------------------------
     # CHANNELS
     # -------------------------------------------------------------------------
@@ -2414,6 +3563,11 @@ Examples:
     ch_schema = channels_sub.add_parser('schema', help='Get channel schema')
     ch_schema.add_argument('--channelid', required=True, help='Channel ID')
     ch_schema.add_argument('--fields', help='Comma-separated fields to return')
+    ch_schema.add_argument('--category', help='Filter by category (e.g., Objects, Backgrounds, Sensors)')
+    ch_schema.add_argument('--subcategory', help='Filter by subcategory (e.g., Aircraft, Vehicles, Ships)')
+    ch_schema.add_argument('--search', help='Case-insensitive search across name, category, subcategory, tooltip, and descriptions')
+    ch_schema.add_argument('--names-only', action='store_true', help='Output only node names (sorted)')
+    ch_schema.add_argument('--list-categories', action='store_true', help='List all available categories and subcategories')
     ch_schema.set_defaults(func=cmd_channels_schema)
 
     # channels nodes
@@ -2612,6 +3766,17 @@ Examples:
     ann_edit.add_argument('--tags', required=True, help='Comma-separated tags')
     ann_edit.set_defaults(func=cmd_annotations_edit)
 
+    # annotations view
+    ann_view = annotations_sub.add_parser('view', help='Generate image with annotations overlayed')
+    ann_view.add_argument('--imagepath', required=True, help='Path to the image file in the dataset directory')
+    ann_view.add_argument('--outdir', required=True, help='Output directory for the annotated image')
+    ann_view.add_argument('--drawtype', default='box_2d', help='Annotation type(s) to draw: box_2d, box_3d, segmentation (comma-separated for multiple)')
+    ann_view.add_argument('--objectids', help='Comma-separated list of object IDs to annotate (filter)')
+    ann_view.add_argument('--objecttypes', help='Comma-separated list of object types to annotate (filter)')
+    ann_view.add_argument('--thickness', type=int, default=1, help='Line thickness for annotations (default: 1)')
+    ann_view.add_argument('--colors', help='JSON dict of object type to RGB color, e.g. \'{"Car": [255, 0, 0]}\'')
+    ann_view.set_defaults(func=cmd_annotations_view)
+
     # -------------------------------------------------------------------------
     # ANNOTATION MAPS
     # -------------------------------------------------------------------------