Skip to content

Plugin System

The cuvis-ai plugin system enables extending the framework with custom nodes and functionality without modifying the core codebase. Distribute your algorithms via Git, share with the community, and maintain independent versioning.

A plugin can come from a tagged Git release or a local checkout. Plugins extend NodeRegistry with external node classes; no core changes required.

Quick Start

from cuvis_ai_core.utils.node_registry import NodeRegistry

registry = NodeRegistry()
registry.load_plugins("configs/plugins/trackeval.yaml")

HOTAMetricNode = registry.get("HOTAMetricNode", instance=registry)

Manifest Shapes

Each plugin manifest uses a plugins: mapping and one of two source styles:

plugins:
  ultralytics:
    repo: "https://github.com/cubert-hyperspectral/cuvis-ai-ultralytics.git"
    tag: "v0.1.0"
    provides:
      - cuvis_ai_ultralytics.node.YOLOPreprocess
      - cuvis_ai_ultralytics.node.YOLO26Detection
      - cuvis_ai_ultralytics.node.YOLOPostprocess

  trackeval:
    repo: "https://github.com/cubert-hyperspectral/cuvis-ai-trackeval.git"
    tag: "v0.1.0"
    provides:
      - cuvis_ai_trackeval.node.HOTAMetricNode

  sam3:
    path: "../../../../cuvis-ai-sam3/sam3-init"
    provides:
      - cuvis_ai_sam3.node.SAM3TextPropagation
  • repo + tag: clone a released plugin into the local cache.
  • path: load a local checkout directly. Relative paths resolve from the manifest directory.
  • provides: list fully-qualified class paths that the plugin exports.

Loading Flow

NodeRegistry.load_plugins() validates the manifest, resolves local paths relative to the manifest file, installs plugin dependencies from pyproject.toml, and registers each provided node class in the instance registry.

Cache and Isolation

  • Git plugins are cached under ~/.cuvis_plugins/.
  • Local-path plugins are loaded from the referenced checkout directly.
  • Plugin nodes are stored per NodeRegistry instance, so one session can load plugins without affecting another.

Loading multiple plugins

Each official plugin ships its own plugins.yaml manifest (see below). When a pipeline needs nodes from more than one plugin, pass each manifest path to NodeRegistry.load_plugins() in turn — there's no need to author a single combined file.

Official Plugin Manifests

Official Plugins

Next steps