arcum42-ComfyUI_SageUtils/docs/planning/node_documentation_tool_plan.md

Node Documentation Extraction Tool Plan

Goal

Create a tool that extracts Sage Utils node metadata from the existing nodes/ implementation and provides:

• node_id
• display_name
• description
• category
• inputs with descriptions
• outputs with descriptions

This tool will support two main use cases:

1. Pull a list of all Sage Utils nodes.
2. Pull detailed metadata for all Sage Utils nodes.

Later, the output can be used to generate documentation and node reference content.

Background

The Sage Utils node implementation already exposes a complete node list in nodes_v3.py.

• nodes_v3.py imports all node modules from nodes/*.py
• Each node module defines a module-level array of node classes, such as AUDIO_NODES, TEXT_NODES, etc.
• NODE_LIST is built by concatenating those arrays.

Each node class includes a define_schema classmethod that returns an io.Schema object. The schema contains the node I/O definitions and should be the authoritative source for node metadata.

Scope

The planned tool should operate on the existing Python node definitions and not require manual metadata annotations outside the node classes.

Inputs

• nodes_v3.py and its imported node modules
• NODE_LIST
• node.define_schema() return values

Outputs

For each node, the tool should emit a structured object with:

• node_id — unique identifier for the node (class name or schema name)
• display_name — human-readable name if available
• description — node description or docstring from the schema
• category — node category if present on the schema
• inputs — list of input definitions with name, type, description, and fallback values where available
• outputs — list of output definitions with name, type, and description

Proposed API

The tool should expose at least two actions:

1. list_nodes()

   • Returns the list of Sage Utils node IDs and display names.

2. get_node_metadata(node_ids=None)

   • Returns full metadata for the requested nodes.
   • If node_ids is omitted, return metadata for all nodes.

Implementation Plan

1. Create a tool module in the Sage Utils codebase under tools/node_metadata_tool.py.
2. Document the tool in okf/tools/ by adding an OKF concept entry in okf/tools/index.md and describing it in okf/tools/available_tools.md.
3. Import NODE_LIST from nodes_v3.py.
4. Iterate over NODE_LIST and inspect each node class.
5. Call node.define_schema() and normalize the returned io.Schema object:
   • extract node_id, display_name, description, and category
   • extract inputs and outputs
   • preserve input/output descriptions from the schema
6. Build a normalized metadata record for each node.
7. Return structured JSON/dictionary-friendly output.

Implementation layout

The tool module should expose a small public API for extraction and support both list and metadata retrieval.

Suggested module shape:

from .nodes_v3 import NODE_LIST
from comfy_api.latest import io


def list_nodes() -> list[dict[str, str]]:
    """Return a shallow list of all Sage Utils nodes."""


def get_node_metadata(node_ids: list[str] | None = None) -> list[dict[str, Any]]:
    """Return full metadata for the requested Sage Utils nodes."""

Tool API contract

• list_nodes()
  • returns [{'node_id': 'Sage_LoadImage', 'display_name': 'Load Image'}]
• get_node_metadata(node_ids=None)
  • returns a list of node metadata objects for either the requested nodes or all nodes if none are supplied

A future wrapper can translate these functions into an AI-run tool interface or a CLI entrypoint.

Extraction details

Node list source

• nodes_v3.py is the single source of truth for available Sage Utils nodes.
• It already imports every node module and constructs NODE_LIST.

Schema inspection

The tool should rely on the define_schema() result rather than parsing source files. This preserves the runtime behavior of nodes and picks up any schema logic expressed in Python.

Fallback behavior

If a node or schema is missing a field:

• use the class name as node_id
• use title or name as display_name
• allow empty description
• allow missing category

Output format

Each node record should look like:

{
  "node_id": "Sage_LoadImage",
  "display_name": "Load Image",
  "description": "Load an image from file or URL.",
  "category": "Image",
  "inputs": [
    {
      "name": "image_path",
      "type": "String",
      "description": "Path or URL of the image to load."
    }
  ],
  "outputs": [
    {
      "name": "image",
      "type": "Image",
      "description": "The loaded image tensor."
    }
  ]
}

Next steps after the tool is available

1. Use the tool output to generate node documentation skeletons.
2. Map extracted metadata into js/docs/ markdown templates.
3. Optionally add automation that updates or validates js/docs/ content based on the extracted schema.

Risks and open questions

• Some nodes may use schema metadata fields differently; the tool should be robust to missing data.
• If define_schema() performs side effects or requires backend resources, the extraction should be sandboxed or invoked in a read-only mode.
• If node names are dynamic or locale-specific, preserve both the class name and schema-provided name.

Deliverables

• docs/planning/node_documentation_tool_plan.md
• A tool implementation in Sage Utils that returns node list and node metadata
• A stable JSON output format for downstream documentation generation
• A follow-up plan for markdown generation from extracted metadata