2Customizable Node System

from __future__ import annotations
from app.components.bases import BaseCanvasNode, PortDef

class MyNode(BaseCanvasNode):
    # Identity
    node_type = "myCustomNode"
    display_name = "My Node"
    description = "Does custom processing"
    category = "custom"        # sidebar group
    icon = "Sparkles"          # Lucide icon name

    # Kind: "block" | "composite" | "control"
    kind = "block"

    # Ports
    input_ports = [
        PortDef(name="text", wire_type="TEXT", description="Input text"),
    ]
    output_ports = [
        PortDef(name="result", wire_type="TEXT", description="Processed output"),
    ]

    # Config (JSON Schema for the properties panel)
    config_schema = {"temperature": {"type": "number", "default": 0.7}}
    default_config = {"temperature": 0.7}

    async def forward(self, inputs: dict, ctx: Any) -> dict:
        text = inputs["text"]
        result = process(text, self.config.get("temperature", 0.7))
        return {"result": result}

async def initialize(self) -> None:
    """Called once before first execution. Load models, allocate GPU memory."""

async def shutdown(self) -> None:
    """Called on teardown. Release resources."""

async def forward(self, inputs: dict, ctx: Any) -> dict:
    prompt = self._build_prompt(inputs)
    self._self_log("prompt", prompt)                       # record what we asked
    response = await llm_complete(prompt)
    self._self_log("tokens_used", response.usage.total_tokens)
    return {"text": response.text}

@classmethod
def _resolve_ports(cls, config: dict) -> tuple[list, list]:
    ports_cfg = config.get("ports", [])
    resolved = [PortDef(p["name"], p["wire_type"], optional=True) for p in ports_cfg]
    # Sink nodes: inputs only
    return (resolved, [])

from typing import ClassVar

class PolicyForwardNode(BaseCanvasNode):
    node_type = "my_policy__forward"
    batched: ClassVar[bool] = True
    batch_dim: ClassVar[str] = "rgb"   # input port carrying the per-sample slot

    input_ports = [
        PortDef(name="rgb", wire_type="IMAGE"),
        PortDef(name="hidden_in", wire_type="ANY"),
    ]
    output_ports = [
        PortDef(name="action", wire_type="ACTION"),
        PortDef(name="hidden_out", wire_type="ANY"),
    ]

@dataclass
class PortDef:
    name: str             # port name (= Handle id)
    wire_type: str        # "IMAGE", "ACTION", "TEXT", "DEPTH", etc.
    description: str = ""
    optional: bool = False  # if False, node won't fire until this port has data

from app.components.bases import NodeUIConfig, ConfigField, DisplayField

class MyNode(BaseCanvasNode):
    ui_config = NodeUIConfig(
        color="amber",           # Tailwind color key ("" = auto from category)
        layout="block",          # "block" | "strip" | "viewer" | "imageGrid" | "note"
        width="",                # explicit width (e.g. "44px" for strip gates)
        min_width="",
        max_width="",
        min_height="",
        rounding="",             # CSS rounding class (e.g. "rounded-r-lg")
        config_fields=[
            ConfigField(
                name="temperature",
                field_type="slider",
                label="Temperature",
                default=0.7,
                min=0.0, max=2.0, step=0.1,
            ),
            ConfigField(
                name="model",
                field_type="select",
                label="Model",
                options=[
                    {"value": "gpt-4o", "label": "GPT-4o"},
                    {"value": "claude-sonnet", "label": "Claude Sonnet"},
                ],
            ),
        ],
        display_fields=[
            DisplayField(
                name="response",
                display_type="log_list",
                data_key="text",
                max_visible=20,
                accumulate=True,
            ),
        ],
    )

from __future__ import annotations
from typing import ClassVar
from app.components.bases import BaseNodeSet

class SamNodeSet(BaseNodeSet):
    name = "sam"
    description = "Segment Anything Model tools"

    # Optional: run this nodeset in its own interpreter via AutoServerApp (ADR-server-001).
    # None = use sys.executable.
    server_python: ClassVar[str | None] = "/path/to/sam/python"

    # Optional: control-plane panel (ADR-server-002) — BaseEnvPanel subclass.
    # WorkspaceComponentRegistry instantiates and registers it on load. Used for
    # episode control, checkpoint selection, etc.
    env_panel: ClassVar[type | None] = None

    # Optional: per-episode timeout for batch eval (ADR-eval-002). The batch
    # runner clamps each episode at max_steps * default_per_step_budget_sec.
    # Habitat ~2.0, LLM-heavy MapGPT ~30.0, framework default 30.0.
    default_per_step_budget_sec: ClassVar[float] = 30.0

    def get_tools(self) -> list:
        return [SegmentTool(), EmbedTool()]

    async def initialize(self, **kwargs) -> None:
        # Load SAM model, allocate GPU memory
        ...

    async def shutdown(self) -> None:
        # Release GPU memory
        ...

    async def get_eval_metadata(self) -> dict:
        # Env nodesets override this to expose env_name, splits,
        # episode_counts, metrics, supports_set_episode, step_budget.
        # Non-env nodesets return {} (default).
        return {}

workspace/
  nodesets/{env,method,policy,model,common,other}/ *.py
                         → BaseNodeSet subclasses, grouped by role (ADR-platform-008;
                           server-mode is per-nodeset via server_python, not a directory)
  policies/        *.py  → BaseCanvasNode subclasses with policy metadata
  nodes/           *.py  → BaseCanvasNode subclasses (registered immediately)

1. WorkspaceComponentRegistry.scan_all()
2. Pass 1 — frozen workspace (Settings.workspace_dir):
   For each subdirectory (nodesets/ with its role buckets, policies/, nodes/):
     a. Import every .py file (or package with __init__.py)
     b. Find concrete subclasses of the target base class
     c. Instantiate and register
3. Pass 2 — active workspace overlay (Settings.active_workspace_dir, optional):
   Same scan against the active dir. register_node()'s last-write-wins on
   NODE_HANDLERS gives Python-resource override; same for _discovered_nodesets.
   None / unset = no Pass 2 = bit-identical behaviour. (ADR-components-009)
4. NodeSets: discovered but NOT eagerly loaded at scan time. They load via
   (a) explicit load_nodeset(name) from the NodeSet Manager page, or
   (b) ensure_nodesets_for_graph(graph_def) — auto-loads every nodeset
       referenced by a graph when the graph is opened or a run is
       dispatched (ADR-components-003).
5. Nodes: registered immediately in NODE_HANDLERS
6. Policies: registered in NODE_HANDLERS + policy registry

POST /api/components/reload
  → WorkspaceComponentRegistry.unregister_all()
  → WorkspaceComponentRegistry.scan_all()
  → invalidate_cache()  # frontend re-fetches node schemas