Actions Reference

Actions are the communication bus of the Nessie platform. Every feature — loading data, rendering the UI, filtering graphs — is a named action handled by one or more plugins. Plugins can dispatch actions to other plugins via context.perform_action().

How Dispatch Works

When platform.perform_action(action_name, payload) is called, the PluginManager finds the first registered plugin that handles that action name and calls plugin.handle(action, context). If multiple plugins handle the same action, the first registered wins (or a PluginPrioritization plugin decides).

Data Actions

load_graph

Load a graph from an external data source. This is the primary entry point for datasource plugins.

Payload: plugin-specific dict (e.g. {"Database Path": "..."})

Returns: Graph

Handled by: Datasource plugins

filter_graph

Apply attribute-based filter expressions and/or a full-text search query to a graph, returning a subgraph.

Payload: {"graph": Graph, "filters": list[FilterExpression], "search": str}

Returns: Graph (subgraph of matching nodes + their edges)

Handled by: nessie-graph-manipulation-plugin

Visualization Actions

visualise_graph

Render a graph to an HTML string (SVG + JavaScript). The returned HTML fragment is injected directly into the page DOM.

Payload: Graph object (the graph to render)

Returns: str — self-contained HTML/SVG fragment

Handled by: Visualizer plugins (e.g. nessie-simple-visualizer-plugin)

render

Produce the complete application HTML page. Called once per HTTP request. Reads all workspace state from Context and inlines CSS, JS, and plugin HTML.

Payload: empty {}

Returns: str — complete HTML document

Handled by: nessie-web

change_visualizer

Switch the active visualizer plugin for the current workspace.

Payload: {"visualizer_name": str}

Returns: None

Handled by: nessie-platform (built-in)

Workspace Actions

open_workspace

Open a new workspace tab by loading a graph from a named datasource plugin.

Payload: {"plugin": str, "payload": dict} — datasource plugin name + its setup payload

Returns: None

switch_workspace

Set a workspace tab as active by index.

Payload: {"index": int}

Returns: None

close_workspace

Close a workspace tab by index.

Payload: {"index": int}

Returns: None

Filter Actions

apply_filters

Re-apply the current active filter stack and search query to the full graph of the active workspace. Updates the displayed graph.

Payload: {}

add_filter

Add a FilterExpression to the active filter stack and re-apply all filters.

Payload: {"filter": FilterExpression | dict}

remove_filter

Remove a specific FilterExpression from the active filter stack.

Payload: {"filter": FilterExpression | dict}

clear_filters

Remove all filters from the active workspace and restore the full graph.

Payload: {}

Set a free-text search query and re-apply all filters with the new query.

Payload: {"query": str}

Console Actions

add_console_message

Append a message to the active workspace's console panel.

Payload: {"message": {"message": str, "type": "ok"|"error"|"info"|"warn"|"input"}}

clear_console

Clear all console messages from the active workspace.

Payload: {}

cli_execute

Execute a Nessie CLI command string (via the nessie-cli plugin). Supports create node, create edge, edit, delete, filter, search, drop graph, clear.

Payload: {"command": str}

Handled by: nessie-cli plugin

Special Actions

PluginPrioritization

Optional. If a plugin handles this action, the PluginManager calls it whenever multiple plugins can handle the same action. The handler receives a list of candidate plugins and returns the best one.

Payload: list[Plugin]

Returns: Plugin

Dispatching Actions from a Plugin

From inside any handler, use context.perform_action() to dispatch actions to other plugins:

from nessie_api.models import Action

def my_handler(action: Action, context):
    # Load a graph from another datasource
    graph = context.perform_action(
        Action("load_graph", {"Database Path": "/tmp/data.db"})
    )

    # Log a message to the UI console
    context.perform_action(
        Action("add_console_message", {
            "message": {"message": "Graph loaded!", "type": "ok"}
        })
    )

    # Dispatch to a specific plugin by name
    html = context.perform_action(
        Action("visualise_graph", graph),
        "Visualiser Simple"   # explicit plugin name
    )