API Reference

Graph nessie_api.models ▶

class Graph(name: str, graph_type: GraphType = GraphType.UNDIRECTED)

The central data structure representing a graph. Holds collections of nodes and edges, and exposes methods to manipulate and query them.

name	str	Human-readable graph name, used as a workspace tab label.
graph_type	GraphType	Whether the graph is DIRECTED or UNDIRECTED. Affects edge arrow rendering.
nodes	list[Node]	Ordered list of all nodes in the graph.
edges	list[Edge]	Ordered list of all edges in the graph.

Method	Returns	Description
add_node(node: Node)	None	Append a node. Raises if a node with the same ID already exists.
get_node(node_id: str)	Node \| None	Look up a node by ID. Returns `None` if not found.
remove_node(node_id: str)	None	Remove a node. Raises `ValueError` if the node has incident edges.
add_edge(edge: Edge)	None	Append an edge. Source and target nodes must already exist in the graph.
get_edge(edge_id: str)	Edge \| None	Look up an edge by ID.
remove_edge(edge_id: str)	None	Remove an edge by ID.
to_dict()	dict	Serialize the graph to a JSON-serializable dict. Used by `nessie-web` to embed state in the HTML page.

GraphType nessie_api.models — Enum ▶

enum GraphType

DIRECTED UNDIRECTED

Passed to Graph() at construction. Controls whether the UI renders arrowheads on edges and whether the force simulation treats edges as directed.

Node nessie_api.models ▶

class Node(id: str, attributes: dict[str, Attribute] = {})

A vertex in the graph. Identified by a string ID that must be unique within its graph. Holds an arbitrary dict of Attribute objects.

id	str	Unique identifier within the graph. Used in edge source/target references.
attributes	dict[str, Attribute]	Key-value attribute store. Keys are attribute names; values are `Attribute` objects.

Method	Returns	Description
add_attribute(attr: Attribute)	None	Add or overwrite an attribute. Key is `attr.name`.
get_attribute(name: str)	Attribute \| None	Retrieve an attribute by name. Returns `None` if absent.
remove_attribute(name: str)	None	Delete an attribute by name.

Edge nessie_api.models ▶

class Edge(id: str, source: Node, target: Node, attributes: dict = {})

A connection between two nodes. Source and target are live Node references (not IDs). Carries its own attribute store.

id	str	Unique identifier within the graph.
source	Node	Origin node of the edge.
target	Node	Destination node of the edge.
attributes	dict[str, Attribute]	Edge metadata (e.g. relationship type, weight).

Method	Returns	Description
add_attribute(attr: Attribute)	None	Add or overwrite an attribute on the edge.
get_attribute(name: str)	Attribute \| None	Retrieve an edge attribute by name.

Attribute nessie_api.models ▶

class Attribute(name: str, value: Any)

A named value attached to a Node or Edge. Values can be str, int, float, or bool. Type is preserved for filter comparisons — the GraphManipulationPlugin attempts type coercion when the filter value type differs.

name	str	Attribute key. Used as the left-hand side in filter expressions.
value	Any	Attribute value. Prefer primitives for filter compatibility.

Action nessie_api.models ▶

class Action(name: str, payload: Any)

A message dispatched through the action bus. The name determines which plugin handler is invoked. The payload carries action-specific data — a dict for most actions, or a Graph object for visualise_graph.

name	str	Action identifier. Must match a key registered in a plugin's `handlers` dict.
payload	Any	Action-specific data. For most actions this is a `dict`. For `visualise_graph` it is a `Graph` object directly.

FilterExpression & FilterOperator nessie_api.models ▶

class FilterExpression(attr_name: str, operator: FilterOperator, value: Any)

A single filter condition. Passed in the filters list of a filter_graph action payload. The GraphManipulationPlugin evaluates each expression against every node's attributes.

attr_name	str	The node attribute key to test.
operator	FilterOperator	The comparison operator.
value	Any	The value to compare against. Type-coercion is attempted if types differ.

Method	Returns	Description
to_json()	dict	Serialize to a JSON-safe dict for embedding in the rendered page state.
from_json(data: dict) classmethod	FilterExpression	Deserialize from a dict (used when the frontend sends a filter back to the server).

enum FilterOperator

EQ == NEQ != LT < LTE <= GT > GTE >=

ConsoleMessage & ConsoleMessageType nessie_api.models ▶

class ConsoleMessage(message: str, type: ConsoleMessageType)

A message displayed in the browser's console panel. Created via context.add_console_message_at() or the add_console_message action.

message	str	The text content displayed in the console.
type	ConsoleMessageType	Controls text color in the UI.

Method	Returns	Description
to_json()	dict	Serialize for embedding in the rendered page state.

enum ConsoleMessageType

OK ERROR INFO WARN INPUT

@plugin decorator & SetupRequirementType nessie_api.models ▶

decorator @plugin(name: str, verbose: bool = False)

Wraps a factory function that returns a plugin descriptor dict. The decorator creates a Plugin instance with the given name, parses the returned dict, and wires up the handler functions. The decorated function becomes callable and returns the Plugin instance.

@plugin("My Plugin")
def my_plugin():
    return {
        "handlers":      {"action_name": handler_fn},
        "requires":      ["other_action"],
        "setup_requires": {"Key": SetupRequirementType.STRING},
    }

enum SetupRequirementType

Defines the type of each setup field shown in the plugin picker UI when the user opens a new workspace.

STRING BOOLEAN NUMBER FILE

Context (protocol) nessie_api.protocols ▶

protocol Context

Abstract interface received by every plugin handler as its second argument. Provides controlled access to platform state. The concrete implementation lives in nessie-platform. Plugin authors should only type-hint against this protocol.

Method	Returns	Description
get_workspace_count()	int	Total number of open workspace tabs. Always ≥ 1 after setup.
get_active_workspace_index()	int \| None	Index of the currently focused workspace tab.
set_active_workspace_index(index: int)	None	Switch the active workspace to the given index.
add_workspace(graph: Graph)	None	Open a new workspace tab with the given graph. Sets it as active.
close_workspace_at(index: int)	None	Close the workspace at the given index.
get_graph_at(index: int)	Graph	Return the currently displayed (filtered) graph at the given workspace index.
get_full_graph_at(index: int)	Graph	Return the unfiltered source graph at the given workspace index.
set_graph_at(index: int, graph: Graph)	None	Replace the displayed (filtered) graph at a workspace.
set_full_graph_at(index: int, graph: Graph)	None	Replace the source graph at a workspace (resets filters).
get_visualised_graph_at(index: int)	str	Call the active visualizer plugin and return the HTML string for the graph at the given index.
get_visualiser_name_at(index: int)	str	Return the name of the active visualizer plugin for a workspace.
set_visualiser_at(index: int, name: str)	None	Switch the active visualizer plugin for a workspace.
get_active_filters_at(index: int)	list[FilterExpression]	Return the list of active filter expressions for a workspace.
add_filter_at(index: int, expr: FilterExpression)	None	Push a filter expression onto a workspace's filter stack.
remove_filter_at(index: int, expr: FilterExpression)	None	Remove a specific filter expression from a workspace.
clear_filters_at(index: int)	None	Remove all filter expressions from a workspace.
get_search_at(index: int)	str	Return the current full-text search query for a workspace.
set_search_at(index: int, query: str)	None	Update the search query for a workspace.
get_console_messages_at(index: int)	list[ConsoleMessage]	Return all console messages for a workspace.
add_console_message_at(index: int, msg: ConsoleMessage)	None	Append a console message to a workspace's console log.
clear_console_messages_at(index: int)	None	Clear all console messages from a workspace.
perform_action(action: Action, plugin_name: str \| None = None)	Any	Dispatch an action to the best-matching plugin. If `plugin_name` is given, route to that specific plugin. Returns the handler's return value.

NoAvailablePluginError nessie_api.models ▶

exception NoAvailablePluginError(message: str)

Raised by PluginManager.get_plugin() when no plugin is registered for the requested action name. Inherits from Exception.

Platform nessie_platform.platform ▶

class Platform()

Top-level entry point for web servers. Instantiate once at startup. Internally creates a PluginManager, a WorkspaceManager, runs plugin discovery, and registers the built-in nessie-platform plugin.

Method	Returns	Description
index()	str	Render and return the complete application HTML for the current state. Calls the `render` action internally. Called on every GET request.
perform_action(action_name: str, payload: dict, plugin_name: str \| None = None)	str	Execute a named action with the given payload, then re-render and return the HTML. Called on every POST `/perform-action` request. If `plugin_name` is given, routes to that specific plugin.
get_plugins(action_name: str)	list[PluginDTO]	Return all plugins that handle the given action. Called by the GET `/plugins` endpoint to populate the UI plugin picker.

PluginManager nessie_platform.plugin_manager ▶

class PluginManager(verbose: bool = False)

Discovers, stores, and dispatches plugins. Maps action names to lists of plugin objects. Internally stores dict[str, list[Plugin]].

Method	Returns	Description
discover_plugins()	None	Load all Python entry points in the `nessie_plugins` group, instantiate each plugin, and call `register_plugin()`.
register_plugin(plugin: Plugin)	None	Register a plugin instance. Indexes it under each action name in its `provided_actions` list.
get_plugin(action_name: str, prioritization: bool = False)	Plugin	Return the first (or prioritized) plugin that handles the action. Raises `NoAvailablePluginError` if none found.
get_specific_plugin(plugin_name: str, action_name: str)	Plugin	Return a specific named plugin for an action. Raises `NoAvailablePluginError` if not found.
get_available_plugins(action_name: str \| None = None)	list[Plugin]	Return all plugins for an action, or all registered plugins if `action_name` is `None`.
check_deps()	None	Verify all plugin dependencies are satisfied. Raises `UnsatisfiedDependencyError` if any plugin's `requires` action is not provided by any registered plugin.
get_unsatisfied_deps()	dict[str, list[str]] \| None	Return a mapping of unsatisfied action → list of plugins that require it. Returns `None` if all deps satisfied.

WorkspaceManager nessie_platform.workspace_manager ▶

class WorkspaceManager()

Manages the ordered list of open workspaces and tracks which one is active. Supports integer indexing (manager[i]) and len().

active_workspace_index int | None Read/write property. Raises IndexError if set to an out-of-range value.

Method	Returns	Description
add_workspace(workspace: Workspace)	None	Append a workspace and set it as active.
remove_workspace_by_index(index: int)	None	Remove the workspace at the given index. Active index is updated to the last remaining workspace, or `None` if none remain.
__getitem__(key: int)	Workspace	Integer index access. Raises `IndexError` for out-of-range keys.
__len__()	int	Number of open workspaces.

PluginDTO nessie_platform.plugin_dto ▶

class PluginDTO(name: str, setup: dict[str, SetupRequirementType])

Lightweight serializable representation of a plugin sent to the browser via GET /plugins. The frontend uses this to populate the plugin picker and build the setup form.

name	str	Plugin display name.
requirements	dict	Maps setup field names to their `SetupRequirementType`.

Method	Returns	Description
to_dict()	dict	Serialize to JSON-safe dict for the HTTP response. Converts `SetupRequirementType` enums to their string values.

Built-in Platform Actions nessie_platform.actions — nessie_platform.constants ▶

The platform registers its own handlers for workspace management, filtering, console, search, and visualization switching. All constants are defined in nessie_platform.constants.

Constant	Value (action name)	Handler
APPLY_FILTERS	`"apply_filters"`	Re-filter active workspace graph using current filters + search.
ADD_FILTER	`"add_filter"`	Push a `FilterExpression` and re-apply.
REMOVE_FILTER	`"remove_filter"`	Pop a specific filter and re-apply.
CLEAR_FILTERS	`"clear_filters"`	Clear all filters; restore full graph.
SEARCH	`"search"`	Set search query and re-apply filters.
OPEN_WORKSPACE	`"open_workspace"`	Load a graph via datasource and add a new workspace tab.
SWITCH_WORKSPACE	`"switch_workspace"`	Change active workspace by index.
CLOSE_WORKSPACE	`"close_workspace"`	Remove a workspace tab by index.
CHANGE_VISUALIZER	`"change_visualizer"`	Switch active visualizer plugin by name.
ADD_CONSOLE_MESSAGE	`"add_console_message"`	Append a `ConsoleMessage` to the active workspace.
CLEAR_CONSOLE	`"clear_console"`	Clear all console messages from the active workspace.
LOAD_GRAPH	`"load_graph"`	Dispatched to datasource plugins.
FILTER_GRAPH	`"filter_graph"`	Dispatched to filter/manipulation plugins.
VISUALIZE_GRAPH	`"visualise_graph"`	Dispatched to visualizer plugins.
RENDER_UI	`"render"`	Dispatched to the web UI plugin.

render() — nessie_web.render nessie_web.render ▶

function render(adapter: Context) → str

Core rendering function. Reads the complete workspace state from adapter (Context), inlines all CSS and JS from _static/, calls adapter.get_visualised_graph_at(i) for the active workspace, and renders the base.html.jinja2 template into a complete HTML document string.

Called by the nessie_web_plugin_handler which is registered as the render action handler.

adapter

Context

Platform context — the only source of state for the render.

plugin nessie_web_plugin()

Decorated with @plugin("Nessie Web"). Registers the render action handler. Entry point: nessie_web_plugin = "nessie_web:nessie_web_plugin".

graph_manipulation_plugin nessie_graph_manipulation_plugin ▶

plugingraph_manipulation_plugin()

Registered as "GraphManipulationPlugin". Handles the filter_graph action.

function_handle_filter_graph(action: Action, context: Context) → Graph

Applies a list of FilterExpression objects against node attributes in sequence, then applies a free-text search query. Returns a new Graph containing only matching nodes and the edges between them.

action.payload["graph"]	Graph	The source graph to filter.
action.payload["filters"]	list[FilterExpression]	Filter rules applied in order. Default: `[]`.
action.payload["search"]	str	Full-text query matched (case-insensitive) against attribute names and values. Default: `""`.

relational_db_plugin & load_graph nessie_relationaldb_datasource_plugin ▶

pluginrelational_db_plugin()

Registered as "SQLite Relational DB". Handles load_graph. Setup fields: Database Path (STRING), Is Directed (BOOLEAN).

functionload_graph(action: Action, context: Context) → Graph

Opens the SQLite database at action.payload["Database Path"], iterates all tables, creates one node per row (ID = tablename_pkvalue), adds all column values as attributes plus a _table attribute, then creates one edge per foreign-key reference with a _relation attribute.

function_validate_db_path(db_path: str) → str

Check existence and file extension (.db, .sqlite, .sqlite3). Raises FileNotFoundError or ValueError.

function_parse(db_path: str, graph_type: GraphType) → Graph

Core parsing logic. Opens the DB in read-only mode, reads PRAGMA table_info and foreign_key_list for each table, then builds nodes in batches of 1000 rows.

npm_dependencies_plugin & async crawler nessie_npm_dependencies_plugin ▶

pluginnpm_dependencies_plugin()

Registered as "NPM Package Dependencies". Handles load_graph. Setup field: Package Name (STRING).

functionload_graph(action: Action, context: Context) → Graph

Calls asyncio.run(build_dependency_graph(action.payload["Package Name"])) and returns the resulting directed graph.

async functionbuild_dependency_graph(root_package: str, max_packages: int = 500) → Graph

Crawls the npm registry starting from root_package. Uses an asyncio.Queue and up to MAX_CONCURRENCY (default 30) async workers. Each worker calls fetch_package(), extracts dependencies, and enqueues new packages. Stops when the queue is empty or max_packages nodes have been visited.

async functionfetch_package(session, package: str) → tuple[dict, dict] | None

Fetches https://registry.npmjs.org/{package}, extracts the latest version's dependencies dict and metadata (version, description, license). Returns None on any network or parsing error.

get_plugin_data & python_file_to_graph nessie_python_datasource_plugin ▶

pluginget_plugin_data()

Registered as "Python sourcing plugin". Handles load_graph. Setup field: Python file path (STRING).

functionpython_file_to_graph(action: Action, context: Context) → Graph

Reads the Python file at action.payload["Python file path"], parses it with ast.parse(), and walks the AST with a ParentVisitor. Creates nodes for classes (class:Name), functions (func:Name), and a module node (module:filename). Creates edges for contains (method, function, nested_class) and call-site (calls) relationships.

classParentVisitor(ast.NodeVisitor)

Internal AST visitor. Tracks current class and function scope. Overrides visit_ClassDef, visit_FunctionDef, and visit_Call to build the graph incrementally.

Interpreter nessie_cli.interpreter ▶

classInterpreter(context: Context, verbose: bool = False)

Parses and executes Nessie CLI command strings using the textX grammar defined in nessie_cli.tx. Dispatches to handler methods by command+subcommand.

Method	Description
execute_command(command: str)	Parse one command string and invoke the appropriate `_execute_*` method.
interpret(commands: list[str])	Execute a list of command strings in order.
_execute_create_node	Handles `create node --id X --property k=v …`. Creates a `Node` and adds it to the full graph, then calls `apply_filters`.
_execute_create_edge	Handles `create edge src tgt --id X`. Looks up source and target nodes by ID, creates an `Edge`.
_execute_edit_node	Handles `edit node --id X --ch_prop k=v --del_prop k`.
_execute_edit_edge	Handles `edit edge --id X --ch_prop k=v`.
_execute_delete_node	Handles `delete node --id X`. Raises if incident edges exist.
_execute_delete_edge	Handles `delete edge --id X`.
_execute_drop_graph	Handles `drop graph`. Replaces source and filtered graph with an empty graph of the same name/type.
_execute_filter	Handles filter `expr`. Uses `Evaluator.simple_evaluate()` to parse the expression, dispatches `clear_filters` then `add_filter` for each result.
_execute_search	Handles `search "query"`. Dispatches the `search` action.
_execute_clear	Handles `clear`. Dispatches the `clear_console` action.

Evaluator nessie_cli.evaluator ▶

classEvaluator(expression)

Evaluates textX-parsed filter expression AST nodes. Supports simple evaluation (returns a list of FilterExpression objects) and full evaluation against a variable context dict.

Method	Returns	Description
simple_evaluate()	list[FilterExpression]	Convert an `AndExpression` or `ComparisonExpression` AST node into `FilterExpression` objects. Used by the `filter` command.
evaluate(context: dict, exp=None)	Any	Evaluate a full expression tree against a context dict (for runtime evaluation with variable substitution).

cli_plugin & Grammar nessie_cli — nessie_cli.nessie_cli.tx ▶

plugincli_plugin()

Registered as "nessie-cli". Handles the cli_execute action. Declares requires: add_console_message, clear_console, add_filter, remove_filter, clear_filters, search.

grammarnessie_cli.tx (textX)

Defines the command language. Key grammar rules:

Command:   command=ID (subcommand=ID)? args* kwargs* ';'?
Argument:  ('`' Expression '`') | STRING | NUMBER | ID
KWParameter: '-'('-'?) key=ID (value=KeyValuePair | value=Argument)?
Expression: OrExpression → AndExpression → ComparisonExpression
          → AdditiveExpression → MultiplicativeExpression → Primary
Primary:   VariableName ('$' name=ID) | NUMBER | STRING | '(' Expression ')'

nessie-api ↗ github

nessie-platform ↗ github

nessie-web ↗ github

nessie-graph-manipulation-plugin ↗ github

nessie-relationaldb-datasource-plugin ↗ github

nessie-npm-dependencies-plugin ↗ github

nessie-python-datasource-plugin ↗ github

nessie-cli (plugin) ↗ github