Capability Discovery API (ai_nn_controller.plugins)

This is the API reference for ai_nn_controller.plugins — despite the similar name, this subpackage is not the runtime plugin system (that’s Plugin Framework API (ai_nn_controller.plugin_framework)). ai_nn_controller.plugins provides two complementary things:

  1. A generic capability-discovery metadata registry (CapabilityMetadata / PluginRegistry) used to catalogue the controller, every loaded app, every loaded runtime plugin, and every app bundle, so they can be introspected at runtime.

  2. The control-application entry-point loader (load_app_entrypoints / bootstrap_application_bundle) — the mechanism that discovers and imports control application packages, analogous to how Plugin Framework API (ai_nn_controller.plugin_framework)’s entry-point loader discovers runtime plugins.

Both are wired into AicController.__init__ and are unrelated to whether a given control app declares required_plugins.

CapabilityMetadata

class ai_nn_controller.plugins.CapabilityMetadata(name, plugin_type, schema='urn:ai-nnc:capability:1', version='1.0.0', compatibility=None, capabilities=None, extra=None)

Dataclass describing one discoverable capability — an app, a runtime plugin, the controller itself, or an app bundle.

Parameters:

  • name – Name of the capability being described

  • plugin_type – Category — e.g. "controller", "app", "plugin", "app_bundle"

  • schema – Schema URN for this metadata format. Default: "urn:ai-nnc:capability:1"

  • version – Version string for this capability. Default: "1.0.0"

  • compatibility – A CompatibilityRange; defaults to 1.0.0–2.x

  • capabilities – List of capability strings (e.g. command names for an app bundle)

  • extra – Free-form dict of additional metadata

to_dict()
Returns:

A plain dict representation, used for JSON responses from the capability-discovery API.

class ai_nn_controller.plugins.CompatibilityRange(min_version='1.0.0', max_version='2.x')

Dataclass describing the version range a capability is compatible with.

PluginRegistry

class ai_nn_controller.plugins.PluginRegistry

Class-level catalogue of registered CapabilityMetadata, keyed internally by "{plugin_type}:{name}".

Methods:

classmethod register(metadata)

Register (or overwrite) a capability entry.

Parameters:

metadata – A CapabilityMetadata instance

classmethod discover(plugin_type=None)
Parameters:

plugin_type – Optional category filter (e.g. "app", "plugin")

Returns:

List of dict (via to_dict()) for every matching entry

AicController populates this registry automatically: it registers itself (plugin_type="controller"), every loaded app (plugin_type="app"), every loaded runtime plugin (plugin_type="plugin"), and every app bundle discovered via entry points (plugin_type="app_bundle"). Call AicController.discover_capabilities() to retrieve the full catalogue at runtime.

Control-Application Entry-Point Loading

Control applications ship as independent Python packages and are discovered at controller startup the same way runtime plugins are (see Plugin Framework API (ai_nn_controller.plugin_framework)), but under a different entry-point group.

ai_nn_controller.plugins.ENTRYPOINT_GROUP

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

ai_nn_controller.plugins.load_app_entrypoints(group='ai_nn_controller.app_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__ after load_plugin_entrypoints(), so that runtime plugins are available before any app’s required_plugins is validated.

ai_nn_controller.plugins.bootstrap_application_bundle(ep=None)

The default entry-point hook used by control application packages. Parses the entry-point name as "bundle_name:app_module:commands_module" (app_module defaults to "aic_app", commands_module defaults to "commands") and:

  1. Imports the commands module and calls its register_specific_commands() (if defined) to register commands with the framework’s command registry.

  2. Calls the commands module’s get_command_capabilities() (if defined) to collect capability strings for the registry entry.

  3. Imports the app module, which runs the @aic_app decorator on any application classes it defines. Guards against re-importing a module that is already running as __main__ (i.e. when launched directly via python3 aic_app.py).

  4. Registers a CapabilityMetadata(plugin_type="app_bundle", ...) entry in PluginRegistry describing the newly loaded app(s).

A control application package declares this in its pyproject.toml:

[project.entry-points."ai_nn_controller.app_init"]
"my_app:aic_app:commands" = "ai_nn_controller.plugins.entrypoints:bootstrap_application_bundle"

See Also