Skip to main content

In-process plugin

Goal: add an in-process plugin that the engine discovers and resolves through a port.

Everything the engine talks to is a plugin: model providers, stores, sandboxes, forges, tools. The engine is a standalone component. It never imports a plugin: it discovers one and speaks through a port. Removing a plugin never breaks the engine build.

Prerequisites​

  • A Python package the engine's environment can import.

Steps​

  1. Add one entry point in the group afe.plugins to your Python package. The engine discovers every installed entry point at startup, and registers the ports the plugin declares.

    # pyproject.toml
    [project.entry-points."afe.plugins"]
    afe-models = "afe_plugins.models:PLUGIN"

  2. Implement the plugin. describe returns a PluginDescriptor, and resolve returns the implementation for a port and name.

    from afe_sdk.plugin import PLUGIN_API, PluginDescriptor, PortSpec

    class MyPlugin:
        def describe(self):
            return PluginDescriptor(
                name="my-plugin",
                api_version=PLUGIN_API,
                ports=[PortSpec(port="models", name="my-provider")],
            )

        def resolve(self, port, name):
            return MyProvider()

    PLUGIN = MyPlugin()

Notes​

apiVersion is the manifest version (afe.dev/v1alpha1). A different major version is refused with a clear error, and so are two plugins on the same (port, name).

Troubleshooting​

plugin 'my-plugin' speaks afe.dev/v2alpha1, the engine speaks afe.dev/v1alpha1 describe returned an api_version with a different major version than the engine's PLUGIN_API. Match your plugin's major version to the engine you install it against.

port models/my-provider is provided by both 'afe-models' and 'my-plugin' Two installed plugins declare the same (port, name). Rename your plugin's port name, or remove the other plugin.

plugin 'my-plugin' has no 'describe' or has no 'resolve' The class assigned to PLUGIN is missing one of the two required methods. Both describe and resolve must exist on the object registered at the entry point.

See also​