Skip to content

Self-improving AI Employees for everyone

refactor(nodes): organize plugin directory to mirror palette groups

trohitg4141ed92a13d
diff --git a/server/nodes/__init__.py b/server/nodes/__init__.py
index 9b47d4cd..80b11990 100644
--- a/server/nodes/__init__.py
+++ b/server/nodes/__init__.py
@@ -1,45 +1,82 @@
-"""Per-node plugin modules (Wave 10.C).
-
-Each ``.py`` file in this package registers one node (or a family of
-closely related nodes) via ``services.node_registry.register_node``. We
-walk the package at import time so every module's ``register_node(...)``
-call runs before the FastAPI app starts serving NodeSpec endpoints.
-
-To add a new node, create ``server/nodes/<name>.py`` with:
-
- from typing import Literal
- from pydantic import Field
- from models.nodes import BaseNodeParams
- from services.node_registry import register_node
-
- class MyParams(BaseNodeParams):
- type: Literal["myNode"]
- query: str = Field(default="", json_schema_extra={"placeholder": "Search..."})
-
- async def handle_my_node(node_id, node_type, params, context):
- return {"success": True, "result": {...}}
-
- register_node(
- type="myNode",
- metadata={
- "displayName": "My Node",
- "icon": "asset:my_icon",
- "group": ["tool"],
- "color": "#8be9fd",
- "componentKind": "square",
- "handles": [
- {"name": "input-main", "kind": "input", "position": "left", "role": "main"},
- {"name": "output-main", "kind": "output", "position": "right", "role": "main"},
- ],
- "description": "...",
- "version": 1,
- },
- input_model=MyParams,
- handler=handle_my_node,
- )
-
-Zero edits required in any other file. The node appears in the editor
-at the next backend restart.
+"""Per-node plugin modules (Wave 11.C).
+
+Each plugin lives in ONE file under the subpackage named after its
+primary palette group. The structure mirrors
+``server/nodes/groups.py`` — every group registered there has a
+matching subdirectory here. Adding a new search node =
+``server/nodes/search/my_search.py`` with a single class.
+
+Auto-discovery is **recursive**: ``pkgutil.walk_packages`` imports
+every ``.py`` under this tree at startup, running every
+``register_node(...)`` or ``BaseNode`` subclass registration as a
+side effect before FastAPI serves its first NodeSpec request.
+
+Layout::
+
+ server/nodes/
+ ├── agent/ # AI Agents (aiAgent, chatAgent, specialized agents)
+ ├── model/ # AI Models (openai, anthropic, gemini, …)
+ ├── skill/ # AI Skills (masterSkill, simpleMemory)
+ ├── tool/ # AI Tools (calculatorTool, currentTimeTool, …)
+ ├── trigger/ # Workflow triggers (webhookTrigger, chatTrigger, …)
+ ├── workflow/ # Workflow control (start, timer, cronScheduler)
+ ├── search/ # Search APIs (braveSearch, serperSearch, perplexitySearch)
+ ├── google/ # Google Workspace (gmail, calendar, drive, …)
+ ├── android/ # Android service nodes
+ ├── whatsapp/ # WhatsApp integration
+ ├── social/ # Unified social messaging (socialSend, socialReceive)
+ ├── code/ # Code executors (python, javascript, typescript)
+ ├── utility/ # HTTP, webhooks, console, proxy, process manager
+ ├── browser/ # Browser automation
+ ├── scraper/ # Web scraping (crawlee, apify, httpScraper)
+ ├── filesystem/ # File I/O + shell + process
+ ├── document/ # Document parsing / chunking / embedding
+ ├── location/ # Google Maps nodes
+ ├── email/ # IMAP/SMTP (emailSend, emailReceive, emailRead)
+ ├── telegram/ # Telegram bot
+ ├── twitter/ # Twitter/X
+ ├── proxy/ # Proxy providers
+ ├── chat/ # Chat send / history
+ ├── scheduler/ # Schedulers
+ ├── text/ # Text generation
+ ├── groups.py # Palette group metadata (label / icon / color)
+ └── __init__.py # This file — recursive discovery.
+
+Legacy bulk-registration files (``agents.py``, ``services.py``,
+``tools.py``, ``triggers.py``, ``utilities.py``) stay at the root
+during 11.C — they hold metadata-only entries for types not yet
+migrated to their subpackage. Each file shrinks as its nodes move
+into their proper folder; gone entirely by end of 11.D.
+
+Canonical plugin file shape::
+
+ # server/nodes/search/my_search.py
+ from pydantic import BaseModel, Field
+ from services.plugin import ActionNode, ApiKeyCredential, Operation
+
+ class MyCredential(ApiKeyCredential):
+ id = "my_service"
+ ...
+
+ class MyParams(BaseModel):
+ query: str
+
+ class MyOutput(BaseModel):
+ results: list = []
+
+ class MyNode(ActionNode):
+ type = "mySearch"
+ display_name = "My Search"
+ group = ("search", "tool")
+ credentials = (MyCredential,)
+ Params = MyParams
+ Output = MyOutput
+
+ @Operation("search")
+ async def search(self, ctx, params): ...
+
+Zero edits required elsewhere. The node appears in the editor at the
+next backend restart, categorised by the primary ``group`` entry.
"""
from __future__ import annotations
@@ -52,21 +89,25 @@ logger = logging.getLogger(__name__)
def _discover() -> list[str]:
- """Import every submodule so its ``register_node`` side effect runs.
- Returns the list of module names imported, for logging."""
+ """Recursively import every ``.py`` under this package so all
+ ``register_node(...)`` + ``BaseNode`` subclass side effects run
+ before anyone asks for a NodeSpec. Private modules (``_foo.py``,
+ ``_subpkg/``) are skipped.
+ """
imported: list[str] = []
- for module_info in pkgutil.iter_modules(__path__):
- name = module_info.name
- if name.startswith("_"):
+ for module_info in pkgutil.walk_packages(__path__, prefix=f"{__name__}."):
+ # Skip private modules and private subpackages anywhere in the path.
+ parts = module_info.name.split(".")
+ if any(part.startswith("_") for part in parts[len(__name__.split(".")):]):
continue
- full_name = f"{__name__}.{name}"
try:
- importlib.import_module(full_name)
- imported.append(name)
+ importlib.import_module(module_info.name)
+ # Short name for logging: drop the package prefix.
+ imported.append(module_info.name.removeprefix(f"{__name__}."))
except Exception:
- logger.exception("Failed to import node plugin %s", full_name)
+ logger.exception("Failed to import node plugin %s", module_info.name)
return imported
_DISCOVERED = _discover()
-logger.info("node plugins loaded: %s", _DISCOVERED or "(none yet)")
+logger.info("node plugins loaded: %d modules", len(_DISCOVERED))
diff --git a/server/nodes/agent/__init__.py b/server/nodes/agent/__init__.py
new file mode 100644
index 00000000..e24d0639
--- /dev/null
+++ b/server/nodes/agent/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'agent' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/android/__init__.py b/server/nodes/android/__init__.py
new file mode 100644
index 00000000..280b448d
--- /dev/null
+++ b/server/nodes/android/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'android' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/browser/__init__.py b/server/nodes/browser/__init__.py
new file mode 100644
index 00000000..c22b2e13
--- /dev/null
+++ b/server/nodes/browser/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'browser' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/chat/__init__.py b/server/nodes/chat/__init__.py
new file mode 100644
index 00000000..1cf210a0
--- /dev/null
+++ b/server/nodes/chat/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'chat' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/code/__init__.py b/server/nodes/code/__init__.py
new file mode 100644
index 00000000..7c80892a
--- /dev/null
+++ b/server/nodes/code/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'code' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/document/__init__.py b/server/nodes/document/__init__.py
new file mode 100644
index 00000000..8ca397bc
--- /dev/null
+++ b/server/nodes/document/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'document' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/email/__init__.py b/server/nodes/email/__init__.py
new file mode 100644
index 00000000..a08e8176
--- /dev/null
+++ b/server/nodes/email/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'email' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/filesystem/__init__.py b/server/nodes/filesystem/__init__.py
new file mode 100644
index 00000000..46183a21
--- /dev/null
+++ b/server/nodes/filesystem/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'filesystem' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/google/__init__.py b/server/nodes/google/__init__.py
new file mode 100644
index 00000000..4d59201b
--- /dev/null
+++ b/server/nodes/google/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'google' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/gmail.py b/server/nodes/google/gmail.py
similarity index 100%
rename from server/nodes/gmail.py
rename to server/nodes/google/gmail.py
diff --git a/server/nodes/gmail_receive.py b/server/nodes/google/gmail_receive.py
similarity index 100%
rename from server/nodes/gmail_receive.py
rename to server/nodes/google/gmail_receive.py
diff --git a/server/nodes/location/__init__.py b/server/nodes/location/__init__.py
new file mode 100644
index 00000000..f851d9ea
--- /dev/null
+++ b/server/nodes/location/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'location' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/model/__init__.py b/server/nodes/model/__init__.py
new file mode 100644
index 00000000..edd80913
--- /dev/null
+++ b/server/nodes/model/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'model' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/proxy/__init__.py b/server/nodes/proxy/__init__.py
new file mode 100644
index 00000000..43113b32
--- /dev/null
+++ b/server/nodes/proxy/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'proxy' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/scheduler/__init__.py b/server/nodes/scheduler/__init__.py
new file mode 100644
index 00000000..f013051b
--- /dev/null
+++ b/server/nodes/scheduler/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'scheduler' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/scraper/__init__.py b/server/nodes/scraper/__init__.py
new file mode 100644
index 00000000..710a820a
--- /dev/null
+++ b/server/nodes/scraper/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'scraper' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/search/__init__.py b/server/nodes/search/__init__.py
new file mode 100644
index 00000000..3b6aa60d
--- /dev/null
+++ b/server/nodes/search/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'search' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/brave_search.py b/server/nodes/search/brave_search.py
similarity index 100%
rename from server/nodes/brave_search.py
rename to server/nodes/search/brave_search.py
diff --git a/server/nodes/skill/__init__.py b/server/nodes/skill/__init__.py
new file mode 100644
index 00000000..f410e6bb
--- /dev/null
+++ b/server/nodes/skill/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'skill' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/social/__init__.py b/server/nodes/social/__init__.py
new file mode 100644
index 00000000..aa9db218
--- /dev/null
+++ b/server/nodes/social/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'social' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/telegram/__init__.py b/server/nodes/telegram/__init__.py
new file mode 100644
index 00000000..104187b6
--- /dev/null
+++ b/server/nodes/telegram/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'telegram' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/text/__init__.py b/server/nodes/text/__init__.py
new file mode 100644
index 00000000..bf4d49eb
--- /dev/null
+++ b/server/nodes/text/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'text' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/tool/__init__.py b/server/nodes/tool/__init__.py
new file mode 100644
index 00000000..a347fc56
--- /dev/null
+++ b/server/nodes/tool/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'tool' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/calculator_tool.py b/server/nodes/tool/calculator_tool.py
similarity index 100%
rename from server/nodes/calculator_tool.py
rename to server/nodes/tool/calculator_tool.py
diff --git a/server/nodes/trigger/__init__.py b/server/nodes/trigger/__init__.py
new file mode 100644
index 00000000..d6f6becc
--- /dev/null
+++ b/server/nodes/trigger/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'trigger' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/webhook_trigger.py b/server/nodes/trigger/webhook_trigger.py
similarity index 100%
rename from server/nodes/webhook_trigger.py
rename to server/nodes/trigger/webhook_trigger.py
diff --git a/server/nodes/twitter/__init__.py b/server/nodes/twitter/__init__.py
new file mode 100644
index 00000000..d1a2d507
--- /dev/null
+++ b/server/nodes/twitter/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'twitter' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/utility/__init__.py b/server/nodes/utility/__init__.py
new file mode 100644
index 00000000..29a033ff
--- /dev/null
+++ b/server/nodes/utility/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'utility' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/whatsapp/__init__.py b/server/nodes/whatsapp/__init__.py
new file mode 100644
index 00000000..201cdf1b
--- /dev/null
+++ b/server/nodes/whatsapp/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'whatsapp' palette group. See ../__init__.py for the package layout."""
diff --git a/server/nodes/workflow/__init__.py b/server/nodes/workflow/__init__.py
new file mode 100644
index 00000000..3786ee74
--- /dev/null
+++ b/server/nodes/workflow/__init__.py
@@ -0,0 +1 @@
+"""Plugins for the 'workflow' palette group. See ../__init__.py for the package layout."""