Skip to main content

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.