Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

refactor plugin loading with shared catalog and safe entrypoint resolver

Cursor Agent444f995363d7
diff --git a/src/core/plugins/__init__.py b/src/core/plugins/__init__.py
index cbb37c9..0a1b2bb 100644
--- a/src/core/plugins/__init__.py
+++ b/src/core/plugins/__init__.py
@@ -1,8 +1,12 @@
+from src.core.plugins.catalog import PluginManifestCatalog
+from src.core.plugins.entrypoints import PluginEntryPointResolver
from src.core.plugins.manager import PluginManager
from src.core.plugins.manifest import PluginManifest, parse_manifest
from src.core.plugins.registry import PluginMeta, PluginRegistryClient
__all__ = [
+ "PluginManifestCatalog",
+ "PluginEntryPointResolver",
"PluginManager",
"PluginManifest",
"PluginMeta",
diff --git a/src/core/plugins/catalog.py b/src/core/plugins/catalog.py
new file mode 100644
index 0000000..4c29379
--- /dev/null
+++ b/src/core/plugins/catalog.py
@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from src.core.plugins.manifest import MANIFEST_FILENAME, PluginManifest, parse_manifest
+
+logger = logging.getLogger("brainapi.plugins.catalog")
+
+
+class PluginManifestCatalog:
+ def __init__(self, plugins_dir: Path, logger_override: Optional[logging.Logger] = None):
+ self.plugins_dir = plugins_dir
+ self._logger = logger_override or logger
+
+ def discover(self, validate: bool = False) -> list[PluginManifest]:
+ if not self.plugins_dir.exists():
+ return []
+
+ manifests: list[PluginManifest] = []
+ for child in sorted(self.plugins_dir.iterdir()):
+ if not child.is_dir():
+ continue
+ manifest_path = child / MANIFEST_FILENAME
+ if not manifest_path.exists():
+ continue
+ try:
+ manifest = parse_manifest(manifest_path)
+ except Exception as exc:
+ self._logger.warning("Failed to parse manifest in '%s': %s", child.name, exc)
+ continue
+
+ if validate:
+ errors = manifest.validate()
+ if errors:
+ self._logger.warning(
+ "Plugin '%s' manifest validation failed: %s",
+ child.name,
+ "; ".join(errors),
+ )
+ continue
+
+ manifests.append(manifest)
+
+ return manifests
diff --git a/src/core/plugins/entrypoints.py b/src/core/plugins/entrypoints.py
new file mode 100644
index 0000000..f5ac2fa
--- /dev/null
+++ b/src/core/plugins/entrypoints.py
@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class PluginEntryPointResolver:
+ def resolve(self, entry_point: str, plugin_dir: Path) -> str:
+ normalized = entry_point.strip().replace("\\", "/")
+ if normalized.endswith(".py"):
+ normalized = normalized[:-3]
+ normalized = normalized.lstrip("./").strip("/")
+ module_name = normalized.replace("/", ".")
+ if module_name.endswith(".__init__"):
+ module_name = module_name[: -len(".__init__")]
+ if module_name == "__init__" or module_name == "":
+ return plugin_dir.name
+ return module_name
diff --git a/src/core/plugins/loader.py b/src/core/plugins/loader.py
index 1ce507b..f5ef1d6 100644
--- a/src/core/plugins/loader.py
+++ b/src/core/plugins/loader.py
@@ -6,9 +6,11 @@ import shutil
import subprocess
import sys
from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
-from src.core.plugins.manifest import MANIFEST_FILENAME, PluginManifest, parse_manifest
+from src.core.plugins.catalog import PluginManifestCatalog
+from src.core.plugins.entrypoints import PluginEntryPointResolver
+from src.core.plugins.manifest import PluginManifest
if TYPE_CHECKING:
from src.core.plugins.context import PluginContext
@@ -17,37 +19,27 @@ logger = logging.getLogger("brainapi.plugins")
class PluginLoader:
- def __init__(self, plugins_dir: Path, context: "PluginContext"):
+ def __init__(
+ self,
+ plugins_dir: Path,
+ context: "PluginContext",
+ manifest_catalog: Optional[PluginManifestCatalog] = None,
+ entry_point_resolver: Optional[PluginEntryPointResolver] = None,
+ ):
self.plugins_dir = plugins_dir
self.context = context
self._loaded: dict[str, PluginManifest] = {}
+ self._manifest_catalog = manifest_catalog or PluginManifestCatalog(
+ plugins_dir=plugins_dir,
+ logger_override=logger,
+ )
+ self._entry_point_resolver = entry_point_resolver or PluginEntryPointResolver()
def discover(self) -> list[PluginManifest]:
if not self.plugins_dir.exists():
logger.info("Plugins directory '%s' does not exist, skipping discovery", self.plugins_dir)
return []
-
- manifests: list[PluginManifest] = []
- for child in sorted(self.plugins_dir.iterdir()):
- if not child.is_dir():
- continue
- manifest_path = child / MANIFEST_FILENAME
- if not manifest_path.exists():
- continue
- try:
- manifest = parse_manifest(manifest_path)
- errors = manifest.validate()
- if errors:
- logger.warning(
- "Plugin '%s' manifest validation failed: %s",
- child.name,
- "; ".join(errors),
- )
- continue
- manifests.append(manifest)
- except Exception as exc:
- logger.warning("Failed to parse manifest in '%s': %s", child.name, exc)
-
+ manifests = self._manifest_catalog.discover(validate=True)
manifests.sort(key=lambda m: m.priority)
return manifests
@@ -91,9 +83,10 @@ class PluginLoader:
if plugin_dir_str not in sys.path:
sys.path.insert(0, plugin_dir_str)
- module_name = manifest.entry_point.replace("/", ".").rstrip(".py")
- if module_name == "__init__":
- module_name = plugin_dir.name
+ module_name = self._entry_point_resolver.resolve(
+ entry_point=manifest.entry_point,
+ plugin_dir=plugin_dir,
+ )
try:
module = importlib.import_module(module_name)
diff --git a/src/core/plugins/manager.py b/src/core/plugins/manager.py
index a666a2d..f831264 100644
--- a/src/core/plugins/manager.py
+++ b/src/core/plugins/manager.py
@@ -5,6 +5,7 @@ import shutil
from pathlib import Path
from typing import Optional
+from src.core.plugins.catalog import PluginManifestCatalog
from src.core.plugins.manifest import MANIFEST_FILENAME, PluginManifest, parse_manifest
from src.core.plugins.registry import PluginMeta, PluginRegistryClient
@@ -21,6 +22,10 @@ class PluginManager:
):
self.plugins_dir = plugins_dir
self.registry_url = registry_url
+ self._manifest_catalog = PluginManifestCatalog(
+ plugins_dir=plugins_dir,
+ logger_override=logger,
+ )
self._registry: Optional[PluginRegistryClient] = None
if registry_url:
self._registry = PluginRegistryClient(
@@ -80,22 +85,7 @@ class PluginManager:
return True
def list_installed(self) -> list[PluginManifest]:
- if not self.plugins_dir.exists():
- return []
-
- manifests: list[PluginManifest] = []
- for child in sorted(self.plugins_dir.iterdir()):
- if not child.is_dir():
- continue
- manifest_path = child / MANIFEST_FILENAME
- if not manifest_path.exists():
- continue
- try:
- manifests.append(parse_manifest(manifest_path))
- except Exception as exc:
- logger.warning("Skipping '%s': %s", child.name, exc)
-
- return manifests
+ return self._manifest_catalog.discover(validate=False)
def list_available(self) -> list[PluginMeta]:
registry = self._ensure_registry()
diff --git a/tests/test_plugin_refactors.py b/tests/test_plugin_refactors.py
new file mode 100644
index 0000000..015f6d4
--- /dev/null
+++ b/tests/test_plugin_refactors.py
@@ -0,0 +1,105 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from src.core.plugins.catalog import PluginManifestCatalog
+from src.core.plugins.entrypoints import PluginEntryPointResolver
+from src.core.plugins.loader import PluginLoader
+from src.core.plugins.manifest import MANIFEST_FILENAME
+
+
+def write_manifest(
+ plugin_dir: Path,
+ *,
+ name: str,
+ version: str = "1.0.0",
+ entry_point: str = "main.py",
+ priority: int = 100,
+) -> None:
+ plugin_dir.mkdir(parents=True, exist_ok=True)
+ content = (
+ f"name: {name}\n"
+ f"version: {version}\n"
+ f"entry_point: \"{entry_point}\"\n"
+ f"priority: {priority}\n"
+ )
+ (plugin_dir / MANIFEST_FILENAME).write_text(content, encoding="utf-8")
+
+
+class PluginEntryPointResolverTests(unittest.TestCase):
+ def test_resolver_handles_python_suffix_safely(self):
+ resolver = PluginEntryPointResolver()
+ resolved = resolver.resolve("mycopy.py", Path("/tmp/demo-plugin"))
+ self.assertEqual(resolved, "mycopy")
+
+ def test_resolver_maps_init_to_package(self):
+ resolver = PluginEntryPointResolver()
+ self.assertEqual(
+ resolver.resolve("__init__.py", Path("/tmp/demo-plugin")),
+ "demo-plugin",
+ )
+ self.assertEqual(
+ resolver.resolve("pkg/__init__.py", Path("/tmp/demo-plugin")),
+ "pkg",
+ )
+
+ def test_resolver_normalizes_relative_paths(self):
+ resolver = PluginEntryPointResolver()
+ resolved = resolver.resolve("./nested/module.py", Path("/tmp/demo-plugin"))
+ self.assertEqual(resolved, "nested.module")
+
+
+class PluginManifestCatalogTests(unittest.TestCase):
+ def test_catalog_can_toggle_validation(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)
+ write_manifest(root / "valid", name="valid", entry_point="main.py")
+ write_manifest(root / "invalid", name="invalid", entry_point="")
+
+ catalog = PluginManifestCatalog(root)
+
+ non_validated = catalog.discover(validate=False)
+ validated = catalog.discover(validate=True)
+
+ self.assertEqual({m.name for m in non_validated}, {"valid", "invalid"})
+ self.assertEqual({m.name for m in validated}, {"valid"})
+
+
+class PluginLoaderRefactorTests(unittest.TestCase):
+ class DummyContext:
+ def __init__(self):
+ self.loaded = []
+
+ def test_loader_discovers_valid_plugins_sorted_by_priority(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)
+ write_manifest(root / "slow", name="slow", priority=20, entry_point="main.py")
+ write_manifest(root / "fast", name="fast", priority=5, entry_point="main.py")
+ write_manifest(root / "broken", name="broken", priority=1, entry_point="")
+
+ loader = PluginLoader(root, self.DummyContext())
+ discovered = loader.discover()
+
+ self.assertEqual([m.name for m in discovered], ["fast", "slow"])
+
+ def test_loader_uses_entry_point_resolver_for_python_module(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ root = Path(tmp)
+ plugin_dir = root / "mycopy"
+ write_manifest(plugin_dir, name="mycopy", entry_point="mycopy.py")
+ (plugin_dir / "mycopy.py").write_text(
+ "def register(context):\n context.loaded.append('mycopy')\n",
+ encoding="utf-8",
+ )
+ manifest = loader_manifest = PluginManifestCatalog(root).discover(validate=True)[0]
+ loader = PluginLoader(root, self.DummyContext())
+
+ loaded = loader.load(loader_manifest)
+
+ self.assertTrue(loaded)
+ self.assertEqual(loader.context.loaded, ["mycopy"])
+ self.assertIn(manifest.name, loader.loaded_plugins)
+
+
+if __name__ == "__main__":
+ unittest.main()