Plugin Framework API (ai_nn_controller.plugin_framework)

This is the API reference for ai_nn_controller.plugin_framework — the runtime plugin system. Plugins are independent Python packages that give control applications a typed, reusable interface to external services (time-series databases, ML model registries, monitoring backends, and so on).

Note

plugin_framework (this page) is distinct from Capability Discovery API (ai_nn_controller.plugins), which is a separate subpackage for capability-discovery metadata and the control-application entry-point loader. See Capability Discovery API (ai_nn_controller.plugins) for that API.

AicPlugin

class ai_nn_controller.plugin_framework.AicPlugin

Base class for all AIC plugins.

plugin_type: str

Category string. Default: "generic".

u_name: str

Unique plugin name, set by the @aic_plugin decorator.

Methods:

classmethod connect()

Initialise the connection to the external service. Called once by AicController at controller startup, after all plugins and apps have been loaded.

classmethod disconnect()

Release resources. Called by AicController at shutdown.

classmethod is_healthy()

Return True if the plugin is operational. Default implementation always returns True — override for real health checks.

Typed Plugin Mixins

These optional base classes define a conventional method surface for common plugin categories. Using them is not required — any AicPlugin subclass works — but they make a plugin’s intent explicit and give consumers a predictable API to call.

class ai_nn_controller.plugin_framework.StoragePlugin

Mixin for plugins that store and retrieve time-series or structured data (e.g. InfluxDB). Sets plugin_type = "storage".

classmethod write(key, value, tags=None)
Parameters:

  • key – Series or record key

  • value – Value to store

  • tags – Optional dict of tags/labels

classmethod read(query)
Parameters:

query – Backend-specific query string

Returns:

List of matching records

class ai_nn_controller.plugin_framework.ModelRegistryPlugin

Mixin for plugins that manage ML model versioning (e.g. MLflow). Sets plugin_type = "model_registry".

classmethod load_model(name, version=None)
Parameters:

  • name – Model name

  • version – Optional specific version; latest if omitted

classmethod save_model(name, model, metrics=None)
Parameters:

  • name – Model name

  • model – Model object to persist

  • metrics – Optional dict of metrics to log alongside the model

class ai_nn_controller.plugin_framework.MonitoringPlugin

Mixin for plugins that push or pull observability metrics (e.g. Prometheus). Sets plugin_type = "monitoring".

classmethod push_metric(name, value, labels=None)
Parameters:

  • name – Metric name

  • value – Metric value

  • labels – Optional dict of labels

classmethod get_metric(name, labels=None)
Parameters:

  • name – Metric name

  • labels – Optional dict of labels to filter by

Returns:

Metric value

@aic_plugin Decorator

@ai_nn_controller.plugin_framework.aic_plugin(name, plugin_type='generic')

Decorator that registers an AicPlugin subclass with PluginManager.

Parameters:

  • name – Unique plugin name. This is the string control apps use in required_plugins and to look the plugin up via cls.plugins[name].

  • plugin_type – Category string — "storage", "model_registry", "monitoring", or "generic" (default).

Raises:

RuntimeError – If a plugin with the same name is already registered.

Example:

from ai_nn_controller.plugin_framework import AicPlugin, aic_plugin

@aic_plugin(name="ConsolePlugin", plugin_type="generic")
class ConsolePlugin(AicPlugin):
    @classmethod
    def connect(cls):
        print("[ConsolePlugin] connected")

    @classmethod
    def log(cls, message: str, level: str = "INFO") -> None:
        print(f"[{level}] {message}")

PluginManager

class ai_nn_controller.plugin_framework.PluginManager

Runtime registry of loaded plugin classes, populated by the @aic_plugin decorator. Analogous to AicManager for control applications.

Methods:

classmethod register(name, plugin_class)

Register a plugin class under name. Called by @aic_plugin.

Raises:

RuntimeError – If name is already registered.

classmethod get(name)
Parameters:

name – Plugin name

Returns:

The registered plugin class, or None if not found

classmethod has(name)
Parameters:

name – Plugin name

Returns:

True if a plugin with that name is registered

classmethod list_plugins(plugin_type=None)
Parameters:

plugin_type – Optional category filter

Returns:

List of registered plugin names

classmethod all_plugins()
Returns:

Dict mapping every registered plugin name to its class

Entry-Point Loading

Plugins ship as independent Python packages and are discovered at controller startup via Python entry points, the same mechanism used for control applications (see Capability Discovery API (ai_nn_controller.plugins)).

ai_nn_controller.plugin_framework.PLUGIN_ENTRYPOINT_GROUP

The entry-point group name: "ai_nn_controller.plugin_init".

ai_nn_controller.plugin_framework.load_plugin_entrypoints(group='ai_nn_controller.plugin_init')

Discover and execute every hook registered under group. Idempotent — safe to call more than once; only runs once per process. Called by AicController.__init__ before load_app_entrypoints() so that required_plugins can be validated before any app starts.

ai_nn_controller.plugin_framework.bootstrap_plugin_bundle(ep=None)

The default entry-point hook used by plugin packages. Parses the entry-point name as "bundle_name:plugin_module" (plugin_module defaults to "aic_plugin") and imports that module, which triggers the @aic_plugin decorator to run and register the plugin class.

A plugin package declares this in its pyproject.toml:

[project.entry-points."ai_nn_controller.plugin_init"]
"my_plugin:aic_plugin" = "ai_nn_controller.plugin_framework.entrypoints:bootstrap_plugin_bundle"

Validation

ai_nn_controller.plugin_framework.validate_app_plugins(app_class)

Check that every plugin name listed in app_class.required_plugins is registered in PluginManager. Called by AicController for each app, after all plugin and app entry points have loaded but before the app starts processing.

Parameters:

app_class – An AicApp subclass

Raises:

RuntimeError – Listing any missing plugin names and the plugins that are available, if required_plugins names anything not registered.

See Also