backend.sdk — backend plugins
The server-side plugin contract: routes, agent tools, /ws channels, lifespan hooks, connectors and dash facades. See the backend plugin SDK.
Also browsable, with search, in the Python reference pane (/pydoc) under Dashboard SDKs.
backend.sdk
AgentTool
AgentTool
A server-side agent tool. Unlike browser tools, its handler runs in the
backend, so it works with no tab attached. `side_effect=True` routes it through
the agent permission gate (read-only tools pass straight through).
AgentToolHandler
AgentToolHandler
Undocumented.
BackendPlugin
BackendPlugin
Base class for a backend plugin. Subclass it, set `manifest`, and implement
`setup` to register capabilities. A plugin module must expose its instance as a
module-level `PLUGIN`.
DashFacadeFactory
DashFacadeFactory
Undocumented.
LifecycleHook
LifecycleHook
Undocumented.
PluginHost
PluginHost
The capability-registration surface handed to a plugin's `setup()`. Every
method namespaces the contribution under the plugin's id so the app can attribute
it. A plugin should call these only from `setup()`.
PluginManifest
PluginManifest
Identity of a backend plugin.
PluginRegistry
PluginRegistry
Everything backend plugins have contributed, aggregated across all plugins.
WsChannelHandler
WsChannelHandler
Undocumented.
load_plugins
load_plugins
Discover and set up every backend plugin into `reg` (the global registry by
default). Idempotent per registry: call `reg.reset()` first to reload. Returns the
registry for convenience.
registry
registry
Undocumented.
backend.sdk.host
BackendPlugin
class BackendPlugin
Base class for a backend plugin. Subclass it, set `manifest`, and implement
`setup` to register capabilities. A plugin module must expose its instance as a
module-level `PLUGIN`.
PluginHost
class PluginHost
The capability-registration surface handed to a plugin's `setup()`. Every
method namespaces the contribution under the plugin's id so the app can attribute
it. A plugin should call these only from `setup()`.
PluginHost.__init__
PluginHost.__init__(self, manifest: PluginManifest, reg: PluginRegistry | None=None) -> None
Undocumented.
PluginHost.add_agent
PluginHost.add_agent(self, spec: AgentSpec) -> None
Register a specialized agent (own system prompt, tool-group scope, and
per-agent `agent.<id>.*` settings). It appears in the roster next to the
built-ins and is addressable from the chat widget and `agent.delegate`.
Built-in agent ids (main, coder, dba, researcher) cannot be overridden.
PluginHost.add_agent_tool
PluginHost.add_agent_tool(self, tool: AgentTool) -> None
Expose a server-side agent tool. Backend plugins win name conflicts in load
order; a name clash with a core tool is the plugin author's responsibility.
PluginHost.add_connector
PluginHost.add_connector(self, connector: Connector) -> None
Expose an external account the user can connect from the home page, and
whose credential the node holds server-side.
Name the connector's agent tools `<connector.id>.*` — the orchestrator groups
tools by their name prefix, so a mismatch silently splits the connector's
tools off from its blurb and guide.
PluginHost.add_dash_facade
PluginHost.add_dash_facade(self, name: str, factory: DashFacadeFactory) -> None
Attach `dash.<name>` in every REPL session (factory builds the object).
PluginHost.add_dataset_source
PluginHost.add_dataset_source(self, source: Any) -> None
Expose a place training material lives (an object satisfying
`backend.modules.datasets.sources.DatasetSource`): search, splits, peek and
locate for one source. It appears in the datasets browser alongside the Hub
and the local files, and a recipe can point at it like any other.
Built-in sources (hub, local, exports, kaggle) win id conflicts.
PluginHost.add_eval_runner
PluginHost.add_eval_runner(self, runner: Any) -> None
Expose a way of executing an eval suite (an object satisfying
`backend.modules.evals.runners.EvalRunner`): which case types it claims and
how it runs them. Results land in the same tables as every other runner's,
so a mixed suite still adds up. Built-ins win id conflicts.
PluginHost.add_music_listener
PluginHost.add_music_listener(self, listener: Any) -> None
Expose a listener (`backend.modules.music.providers.MusicListener`): told
what played (scrobbling) and asked what's similar (the DJ and radio).
PluginHost.add_music_source
PluginHost.add_music_source(self, source: Any) -> None
Expose a music source (satisfying
`backend.modules.music.providers.MusicSource`): `search()` returns
candidates, `fetch()` downloads one into the library. The agent's
`music.play` and the import resolver use it with no new tools. Reusing a
built-in's id (`youtube`) replaces it.
PluginHost.add_playlist_importer
PluginHost.add_playlist_importer(self, importer: Any) -> None
Expose a playlist importer (`backend.modules.music.providers.
PlaylistImporter`): an account that lists playlists, or a file format it
parses. Imported tracks are resolved and downloaded by the music library.
PluginHost.add_recipe_backend
PluginHost.add_recipe_backend(self, backend: Any) -> None
Expose a training framework (an object satisfying
`backend.modules.training.backends.base.RecipeBackend`): which tasks it can
train, which knobs it takes, and the code it emits for them.
The field catalog it returns is validated against the project venv by the
same introspection every built-in backend goes through, so a knob the
installed library does not accept is dropped from the emitted code and shown
as dropped rather than emitted hopefully. Built-ins (trl, unsloth,
torchtitan, nanotron) win id conflicts.
PluginHost.add_router
PluginHost.add_router(self, router: APIRouter, *, prefix: str | None=None) -> None
Mount a FastAPI router. Default prefix is `/api/plugins/<id>`; pass an
explicit `prefix` (joined under `/api`) to override.
PluginHost.add_search_provider
PluginHost.add_search_provider(self, provider: Any) -> None
Expose a web-search provider (an object satisfying
`backend.modules.search.base.SearchProvider`): one `search(query, ...)` that
returns ranked `SearchResult`s. It joins the fan-out and rank fusion
alongside the built-ins, so a plugin's provider is indistinguishable from
Tavily or the node's own crawl index. Reusing a built-in's id overrides it.
PluginHost.add_training_provider
PluginHost.add_training_provider(self, provider: Any) -> None
Expose a training environment provider (an object satisfying
`backend.modules.training.providers.base.EnvironmentProvider`): search,
resolve, fetch, and scaffold one kind of trainable environment. Built-in
providers (kaggle, huggingface, gymnasium) win id conflicts.
PluginHost.add_ws_channel
PluginHost.add_ws_channel(self, channel: str, handler: WsChannelHandler) -> None
Handle a new channel on the shared `/ws` socket. Built-in channels
(`agent`, `collab`, …) take precedence; pick a unique channel name.
PluginHost.manifest
PluginHost.manifest(self) -> PluginManifest
Undocumented.
PluginHost.on_shutdown
PluginHost.on_shutdown(self, hook: LifecycleHook) -> None
Run `hook` when the app shuts down. Sync or async.
PluginHost.on_startup
PluginHost.on_startup(self, hook: LifecycleHook) -> None
Run `hook` when the app starts (inside the lifespan). Sync or async.
PluginHost.owner_id
PluginHost.owner_id(self) -> str
The id every contribution is recorded under, for unloading.
BackendPlugin.setup
BackendPlugin.setup(self, host: PluginHost) -> None
Register this plugin's capabilities via `host`.
backend.sdk.loader
load_plugins
load_plugins(*, extra_dirs: list[Path] | None=None, reg: PluginRegistry | None=None) -> PluginRegistry
Discover and set up every backend plugin into `reg` (the global registry by
default). Idempotent per registry: call `reg.reset()` first to reload. Returns the
registry for convenience.
backend.sdk.module_manifest
ManifestError
class ManifestError
A manifest that cannot describe a loadable module. The message names the field.
ModuleManifest
class ModuleManifest
Undocumented.
PySpec
class PySpec
Undocumented.
Standalone
class Standalone
Undocumented.
ToolGroup
class ToolGroup
Undocumented.
WebSpec
class WebSpec
Undocumented.
ModuleManifest.owns_tool
ModuleManifest.owns_tool(self, tool_name: str) -> bool
Whether `tool_name`'s group (the text before the first dot) is declared.
parse_manifest
parse_manifest(data: dict[str, Any]) -> ModuleManifest
Validate and parse a manifest dict (either shape). Raises `ManifestError`.
read_manifest
read_manifest(package_dir: Path) -> ModuleManifest | None
The manifest in `package_dir` (module manifest preferred), or None if it has none.
Raises `ManifestError` for a manifest that exists but is invalid, and also when the
id does not equal the directory name (the id *is* the install location).
ModuleManifest.to_json
ModuleManifest.to_json(self) -> dict[str, Any]
The camelCase wire shape the frontend reads (`ModulePackageManifest`).
backend.sdk.module_scan
ModuleDescriptor
class ModuleDescriptor
A discovered module package: its manifest and where it came from.
ScanResult
class ScanResult
Undocumented.
ModuleDescriptor.builtin
ModuleDescriptor.builtin(self) -> bool
Undocumented.
builtin_modules_dir
builtin_modules_dir() -> Path
`modules/` beside `backend/` — in a checkout and in the packaged runtime alike.
ModuleDescriptor.id
ModuleDescriptor.id(self) -> str
Undocumented.
installed_modules_dir
installed_modules_dir() -> Path
Undocumented.
load_order
load_order(manifests: Iterable[ModuleManifest]) -> tuple[list[str], list[str]]
Topologically order modules so dependencies load first.
Edges come from `dependsOn` and from `requires` → whichever module `provides` that
contract. Ties keep input order, so the result is deterministic. Returns
``(order, problems)``: a cycle does not fail the load — its members are appended
in input order and named in `problems`, because a running app with a logged cycle
beats a blank one. Dependencies on modules that aren't present are reported too.
ModuleDescriptor.load_python
ModuleDescriptor.load_python(self) -> Any | None
Import and return the module's Python entry object (``MODULE``), or None
for a web-only module.
scan_modules
scan_modules(*, builtin_dir: Path | None=None, extra_dirs: Iterable[Path]=(), installed_dir: Path | None=None, entry_points: bool=True) -> ScanResult
Discover every module package. Never raises: bad packages land in `errors`.
backend.sdk.registry
PluginRegistry
class PluginRegistry
Everything backend plugins have contributed, aggregated across all plugins.
PluginRegistry.dispatch_ws
PluginRegistry.dispatch_ws(self, conn: Any, channel: str, message: dict[str, Any]) -> bool
Route a `/ws` frame to a plugin channel handler. Returns True if handled.
PluginRegistry.invoke_agent_tool
PluginRegistry.invoke_agent_tool(self, name: str, args: dict[str, Any]) -> Any
Run a plugin agent tool by name, awaiting an async handler. Failures come
back as an `{'error': ...}` value so one bad tool can't break a turn.
PluginRegistry.own
PluginRegistry.own(self, owner: str, kind: str, key: Any) -> None
Record that `owner` contributed `key` to `kind`.
PluginRegistry.owner_of_tool
PluginRegistry.owner_of_tool(self, name: str) -> str | None
Undocumented.
PluginRegistry.provide
PluginRegistry.provide(self, owner: str, contract: str, impl: Any) -> None
Undocumented.
PluginRegistry.provider_tools
PluginRegistry.provider_tools(self, *, grouped: bool | None=None) -> list[dict[str, Any]]
Plugin agent tools as provider tool definitions (for the model).
`grouped=None` returns all (back-compat). `grouped=False` returns only
always-core tools (no `group`); `grouped=True` returns only the ones
disclosed under a group, for the progressive-disclosure pool.
PluginRegistry.reset
PluginRegistry.reset(self) -> None
Drop all registrations (used between test loads).
PluginRegistry.run_shutdown
PluginRegistry.run_shutdown(self, owner: str | None=None) -> None
Undocumented.
PluginRegistry.run_startup
PluginRegistry.run_startup(self, owner: str | None=None) -> None
Run startup hooks — all of them at app start, or one owner's when it is
loaded into an app that is already running.
PluginRegistry.run_ws_disconnect
PluginRegistry.run_ws_disconnect(self, conn: Any) -> None
Tell every module a `/ws` connection closed. Never raises.
PluginRegistry.service
PluginRegistry.service(self, contract: str) -> Any | None
Undocumented.
PluginRegistry.unregister_owner
PluginRegistry.unregister_owner(self, owner: str) -> list[tuple[str, Any]]
Remove everything `owner` contributed. Idempotent; returns what was removed.
A key another owner has since replaced is left alone — the later registration
won, and unloading the earlier one must not take it out.
backend.sdk.types
AgentSpec
class AgentSpec
One agent persona in the roster — a fully separate loop with its own system
prompt, tool scope, per-agent settings (`agent.<id>.*`), and conversation
history. The built-in roster (main/coder/dba/researcher) lives in
`backend.modules.agent.roster`; plugins add their own via `host.add_agent`.
`tool_groups=None` means unrestricted (every group loadable — the main
orchestrator); a list restricts the agent to those groups. `preload_groups`
are active from the first round (specialized agents skip keyword preloading,
their scope is already known).
AgentTool
class AgentTool
A server-side agent tool. Unlike browser tools, its handler runs in the
backend, so it works with no tab attached. `side_effect=True` routes it through
the agent permission gate (read-only tools pass straight through).
Connector
class Connector
An external account the node can connect to and hold credentials for.
`id` MUST equal the namespace of the agent tools it enables (`github` ->
`github.searchCode`), because the orchestrator derives a tool's group from its
name prefix (`_group_of`) — the `AgentTool.group` field does not name the group.
Keeping them equal is what lets one connector definition feed both the home tile
and the agent's tool-group catalog.
ConnectorAccount
class ConnectorAccount
The connected identity, for display only — never a credential.
ConnectorScope
class ConnectorScope
One permission the connector asks the provider for, in the user's words.
Rendered in the tile popover so "what did I grant this thing" is answerable
without reading the source.
ConnectorStatus
class ConnectorStatus
A connector's current state. `error` is for a connection that exists but is
unusable (revoked token, unreadable credential) — distinct from `connected=False`,
which means "never connected". Collapsing the two is what makes a broken
integration look like an unconfigured one.
PluginManifest
class PluginManifest
Identity of a backend plugin.
AgentTool.meta
AgentTool.meta(self) -> dict[str, Any]
Permission-gate metadata (matches the shape the orchestrator expects).
AgentTool.provider_tool
AgentTool.provider_tool(self) -> dict[str, Any]
The provider (Ollama/OpenAI) tool definition for this tool.
Connector.resolve_guide
Connector.resolve_guide(self) -> str | None
The guide text, calling the factory if one was given.