backend.ai-plugin 25.15.2__py3-none-any.whl

ai/backend/plugin/VERSION

@@ -0,0 +1 @@
+25.15.2

ai/backend/plugin/__init__.py

@@ -0,0 +1,3 @@
+from pathlib import Path
+
+__version__ = (Path(__file__).parent / "VERSION").read_text().strip()

ai/backend/plugin/cli.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import enum
+import itertools
+import json
+import logging
+from collections import defaultdict
+from typing import Self
+
+import click
+import colorama
+import tabulate
+from colorama import Fore, Style
+
+from ai.backend.logging import AbstractLogger, LocalLogger, LogLevel
+
+from .entrypoint import (
+    prepare_wheelhouse,
+    scan_entrypoint_from_buildscript,
+    scan_entrypoint_from_package_metadata,
+    scan_entrypoint_from_plugin_checkouts,
+)
+
+log = logging.getLogger(__spec__.name)
+
+
+class FormatOptions(enum.StrEnum):
+    CONSOLE = "console"
+    JSON = "json"
+
+
+class CLIContext:
+    _logger: AbstractLogger
+
+    def __init__(self, log_level: LogLevel) -> None:
+        self.log_level = log_level
+
+    def __enter__(self) -> Self:
+        self._logger = LocalLogger(log_level=self.log_level)
+        self._logger.__enter__()
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self._logger.__exit__()
+
+
+@click.group()
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Set the logging level to DEBUG",
+)
+@click.pass_context
+def main(
+    ctx: click.Context,
+    debug: bool,
+) -> None:
+    """The root entrypoint for unified CLI of the plugin subsystem"""
+    log_level = LogLevel.DEBUG if debug else LogLevel.NOTSET
+    ctx.obj = ctx.with_resource(CLIContext(log_level))
+
+
+@main.command()
+@click.argument("group_name")
+@click.option(
+    "--format",
+    type=click.Choice([*FormatOptions]),
+    default=FormatOptions.CONSOLE,
+    show_default=True,
+    help="Set the output format.",
+)
+def scan(
+    group_name: str,
+    format: FormatOptions,
+) -> None:
+    sources: dict[str, set[str]] = defaultdict(set)
+    rows = []
+
+    prepare_wheelhouse()
+    for source, entrypoint in itertools.chain(
+        (("buildscript", item) for item in scan_entrypoint_from_buildscript(group_name)),
+        (("plugin-checkout", item) for item in scan_entrypoint_from_plugin_checkouts(group_name)),
+        (("python-package", item) for item in scan_entrypoint_from_package_metadata(group_name)),
+    ):
+        sources[entrypoint.name].add(source)
+        rows.append((source, entrypoint.name, entrypoint.module))
+    rows.sort(key=lambda row: (row[2], row[1], row[0]))
+
+    match format:
+        case FormatOptions.CONSOLE:
+            if not rows:
+                print(f"No plugins found for the entrypoint {group_name!r}")
+                return
+            colorama.init(autoreset=True)
+            ITALIC = colorama.ansi.code_to_chars(3)
+            STRIKETHR = colorama.ansi.code_to_chars(9)
+            src_style = {
+                "buildscript": Fore.LIGHTYELLOW_EX,
+                "plugin-checkout": Fore.LIGHTGREEN_EX,
+                "python-package": Fore.LIGHTBLUE_EX,
+            }
+            display_headers = (
+                f"{ITALIC}Source{Style.RESET_ALL}",
+                f"{ITALIC}Name{Style.RESET_ALL}",
+                f"{ITALIC}Module Path{Style.RESET_ALL}",
+                f"{ITALIC}Note{Style.RESET_ALL}",
+            )
+            display_rows = []
+            duplicates = set()
+            warnings: dict[str, str] = dict()
+            for source, name, module_path in rows:
+                note = ""
+                name_style = Style.BRIGHT
+                has_plugin_checkout = "plugin-checkout" in sources[name]
+                duplication_threshold = 2 if has_plugin_checkout else 1
+                if len(sources[name]) > duplication_threshold:
+                    duplicates.add(name)
+                    name_style = Fore.RED + Style.BRIGHT
+                if source == "plugin-checkout":
+                    name_style = Style.DIM + STRIKETHR
+                    if "python-package" in sources[name]:
+                        note = "Loaded via the python-package source"
+                    else:
+                        note = "Ignored when loading plugins unless installed as editable"
+                display_rows.append((
+                    f"{src_style[source]}{source}{Style.RESET_ALL}",
+                    f"{name_style}{name}{Style.RESET_ALL}",
+                    module_path,
+                    note,
+                ))
+            print(tabulate.tabulate(display_rows, display_headers))
+            for name, msg in warnings.items():
+                print(msg)
+            if duplicates:
+                duplicate_list = ", ".join(duplicates)
+                print(
+                    f"\n{Fore.LIGHTRED_EX}\u26a0 Detected duplicated entrypoint(s): {Style.BRIGHT}{duplicate_list}{Style.RESET_ALL}"
+                )
+                if "accelerator" in group_name:
+                    print(
+                        f"{Fore.LIGHTRED_EX}  You should check [agent].allow-compute-plugins in "
+                        f"agent.toml to activate only one accelerator implementation for each name.{Style.RESET_ALL}"
+                    )
+        case FormatOptions.JSON:
+            output_rows = []
+            for source, name, module_path in rows:
+                output_rows.append({
+                    "source": source,
+                    "name": name,
+                    "module_path": module_path,
+                })
+            print(json.dumps(output_rows, indent=2))

ai/backend/plugin/entrypoint.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import ast
+import collections
+import configparser
+import itertools
+import logging
+import os
+import sys
+import zipfile
+from importlib.metadata import EntryPoint, entry_points
+from pathlib import Path
+from typing import Iterable, Iterator, Optional
+
+log = logging.getLogger(__spec__.name)
+
+
+def scan_entrypoints(
+    group_name: str,
+    allowlist: Optional[set[str]] = None,
+    blocklist: Optional[set[str]] = None,
+) -> Iterator[EntryPoint]:
+    if blocklist is None:
+        blocklist = set()
+    existing_names: dict[str, EntryPoint] = {}
+
+    prepare_wheelhouse()
+    for entrypoint in itertools.chain(
+        scan_entrypoint_from_buildscript(group_name),
+        scan_entrypoint_from_package_metadata(group_name),
+    ):
+        if allowlist is not None and not match_plugin_list(entrypoint.value, allowlist):
+            continue
+        if match_plugin_list(entrypoint.value, blocklist):
+            continue
+        if existing_entrypoint := existing_names.get(entrypoint.name, None):
+            if existing_entrypoint.value == entrypoint.value:
+                # Allow if the same plugin is scanned multiple times.
+                # This may happen if:
+                # - A plugin is installed via `./py -m pip install -e ...`
+                # - The unified venv is re-exported *without* `./py -m pip uninstall ...`.
+                # - Adding PYTHONPATH with plugin src directories in `./py` results in
+                #   *duplicate* scan results from the remaining `.egg-info` directory (pkg metadata)
+                #   and the `setup.cfg` scan results.
+                # TODO: compare the plugin versions as well? (need to remember version with entrypoints)
+                continue
+            else:
+                raise RuntimeError(
+                    f"Detected a duplicate plugin entrypoint name {entrypoint.name!r} "
+                    f"from {existing_entrypoint.value} and {entrypoint.value}",
+                )
+        existing_names[entrypoint.name] = entrypoint
+        yield entrypoint
+
+
+def match_plugin_list(entry_path: str, plugin_list: set[str]) -> bool:
+    """
+    Checks if the given module attribute reference is in the plugin_list.
+    The plugin_list items are assumeed to be prefixes of package import paths
+    or the package namespaces.
+    """
+    mod_path = entry_path.partition(":")[0]
+    for block_pattern in plugin_list:
+        if mod_path.startswith(block_pattern + ".") or mod_path == block_pattern:
+            return True
+    return False
+
+
+def scan_entrypoint_from_package_metadata(group_name: str) -> Iterator[EntryPoint]:
+    log.debug("scan_entrypoint_from_package_metadata(%r)", group_name)
+
+    yield from entry_points().select(group=group_name)
+
+
+_default_glob_excluded_patterns = [
+    "ai/backend/webui",
+    "ai/backend/web/static",
+    "ai/backend/runner",
+    "ai/backend/kernel",
+    "wheelhouse",
+    "tools",
+]
+
+_optimized_glob_search_patterns = {
+    # These patterns only apply to scanning BUILD files in dev setups and pex distributions.
+    # They do not affect standard package entrypoint searches.
+    # NOTE: most entrypoint declaration in BUILD files are in the package's top-level only!
+    "backendai_cli_v10": ["ai/backend/*", "ai/backend/appproxy/*"],
+    "backendai_network_manager_v1": ["ai/backend/*"],
+    "backendai_event_dispatcher_v20": ["ai/backend/*", "ai/backend/appproxy/*"],
+    "backendai_stats_monitor_v20": ["ai/backend/*", "ai/backend/appproxy/*"],
+    "backendai_error_monitor_v20": ["ai/backend/*", "ai/backend/appproxy/*"],
+    "backendai_hook_v20": ["ai/backend/*"],
+    "backendai_webapp_v20": ["ai/backend/*"],
+    "backendai_scheduler_v10": ["ai/backend/manager"],
+    "backendai_agentselector_v10": ["ai/backend/manager"],
+}
+
+
+def _glob(
+    base_path: Path,
+    filename: str,
+    excluded_patterns: Iterable[str],
+    match_patterns: Iterable[str] | None = None,
+) -> Iterator[Path]:
+    q: collections.deque[tuple[Path, bool]] = collections.deque()
+    assert base_path.is_dir()
+    q.append((base_path, False))
+    while q:
+        search_path, suffix_match = q.pop()
+
+        # Check if current directory matches any pattern and we should yield files from it
+        current_matches = False
+        if match_patterns is not None:
+            current_matches = any(search_path.match(pattern) for pattern in match_patterns)
+
+        for item in search_path.iterdir():
+            if item.is_dir():
+                if item.name == "__pycache__":
+                    continue
+                if item.name.startswith("."):
+                    continue
+                if any(item.match(pattern) for pattern in excluded_patterns):
+                    continue
+
+                # Determine if we should queue this directory
+                should_queue = False
+                new_suffix_match = False
+
+                if match_patterns is None:
+                    # No patterns specified - queue all non-excluded directories
+                    should_queue = True
+                    new_suffix_match = False
+                elif not suffix_match:
+                    # Haven't found a matching directory yet - check if this one matches
+                    if any(item.match(pattern) for pattern in match_patterns):
+                        should_queue = True
+                        new_suffix_match = True
+                    else:
+                        # Keep searching - queue without suffix match
+                        should_queue = True
+                        new_suffix_match = False
+                else:
+                    # Already found a matching directory - only queue if this also matches
+                    if any(item.match(pattern) for pattern in match_patterns):
+                        should_queue = True
+                        new_suffix_match = True
+
+                if should_queue:
+                    q.append((item, new_suffix_match))
+            else:
+                if item.name == filename:
+                    # Yield file if no patterns or current directory matches
+                    if match_patterns is None or current_matches:
+                        yield item
+
+
+def scan_entrypoint_from_buildscript(group_name: str) -> Iterator[EntryPoint]:
+    entrypoints = {}
+    # Scan self-exported entrypoints when executed via pex.
+    ai_backend_ns_path = Path(__file__).parent.parent
+    log.debug(
+        "scan_entrypoint_from_buildscript(%r): Namespace path: %s", group_name, ai_backend_ns_path
+    )
+    match_patterns = _optimized_glob_search_patterns.get(group_name, None)
+    # First, it is invoked in PEX or temporary test environment generated by Pantsbuild.
+    # In the test environment, BUILD files are NOT copied, so the plugin discovery will rely on the
+    # followed build-root search below.
+    for buildscript_path in _glob(
+        ai_backend_ns_path, "BUILD", _default_glob_excluded_patterns, match_patterns
+    ):
+        for entrypoint in extract_entrypoints_from_buildscript(group_name, buildscript_path):
+            entrypoints[entrypoint.name] = entrypoint
+    if os.environ.get("SCIE", None) is None:
+        # Override with the entrypoints found in the current build-root directory.
+        try:
+            build_root = find_build_root()
+        except ValueError:
+            pass
+        else:
+            src_path = build_root / "src"
+            log.debug("scan_entrypoint_from_buildscript(%r): current src: %s", group_name, src_path)
+            for buildscript_path in _glob(
+                src_path, "BUILD", _default_glob_excluded_patterns, match_patterns
+            ):
+                for entrypoint in extract_entrypoints_from_buildscript(
+                    group_name, buildscript_path
+                ):
+                    entrypoints[entrypoint.name] = entrypoint
+    else:
+        log.debug(
+            "scan_entrypoint_from_buildscript(%r): skipping 'src' when executed inside the SCIE environment",
+            group_name,
+        )
+    yield from entrypoints.values()
+
+
+def scan_entrypoint_from_plugin_checkouts(group_name: str) -> Iterator[EntryPoint]:
+    entrypoints = {}
+    try:
+        build_root = find_build_root()
+    except ValueError:
+        pass
+    else:
+        plugins_path = build_root / "plugins"
+        log.debug(
+            "scan_entrypoint_from_plugin_checkouts(%r): plugin parent dir: %s",
+            group_name,
+            plugins_path,
+        )
+        # For cases when plugins use Pants
+        for buildscript_path in _glob(plugins_path, "BUILD", _default_glob_excluded_patterns):
+            for entrypoint in extract_entrypoints_from_buildscript(group_name, buildscript_path):
+                entrypoints[entrypoint.name] = entrypoint
+        # For cases when plugins use standard setup.cfg
+        for setup_cfg_path in _glob(plugins_path, "setup.cfg", _default_glob_excluded_patterns):
+            for entrypoint in extract_entrypoints_from_setup_cfg(group_name, setup_cfg_path):
+                if entrypoint.name not in entrypoints:
+                    entrypoints[entrypoint.name] = entrypoint
+        # TODO: implement pyproject.toml scanner
+    yield from entrypoints.values()
+
+
+def prepare_wheelhouse(base_dir: Path | None = None) -> None:
+    if base_dir is None:
+        base_dir = Path.cwd()
+    for whl_path in (base_dir / "wheelhouse").glob("*.whl"):
+        extracted_path = whl_path.with_suffix("")  # strip the extension
+        log.debug("prepare_wheelhouse(): loading %s", whl_path)
+        if not extracted_path.exists():
+            with zipfile.ZipFile(whl_path, "r") as z:
+                z.extractall(extracted_path)
+        decoded_path = os.fsdecode(extracted_path)
+        if decoded_path not in sys.path:
+            sys.path.append(decoded_path)
+
+
+def find_build_root(path: Optional[Path] = None) -> Path:
+    if env_build_root := os.environ.get("BACKEND_BUILD_ROOT", None):
+        return Path(env_build_root)
+    cwd = Path.cwd() if path is None else path
+    while True:
+        if (cwd / "BUILD_ROOT").exists():
+            return cwd
+        cwd = cwd.parent
+        if cwd.parent == cwd:
+            # reached the root directory
+            break
+    raise ValueError("Could not find the build root directory")
+
+
+def extract_entrypoints_from_buildscript(
+    group_name: str,
+    buildscript_path: Path,
+) -> Iterator[EntryPoint]:
+    try:
+        tree = ast.parse(buildscript_path.read_bytes())
+    except IsADirectoryError:
+        # In macOS, "build" directories generated by build scripts of vendored repositories
+        # are indistinguishable with "BUILD" files because macOS' default filesystem setting
+        # ignores the cases of filenames.
+        # Let's simply skip over in such cases.
+        return
+    for node in tree.body:
+        if (
+            isinstance(node, ast.Expr)
+            and isinstance(node.value, ast.Call)
+            and isinstance(node.value.func, ast.Name)
+            and node.value.func.id == "python_distribution"
+        ):
+            for kwarg in node.value.keywords:
+                if kwarg.arg == "entry_points":
+                    raw_data = ast.literal_eval(kwarg.value)
+                    for key, raw_entry_points in raw_data.items():
+                        if key != group_name:
+                            continue
+                        for name, ref in raw_entry_points.items():
+                            try:
+                                yield EntryPoint(name=name, value=ref, group=group_name)
+                            except ValueError:
+                                pass
+
+
+def extract_entrypoints_from_setup_cfg(
+    group_name: str,
+    setup_cfg_path: Path,
+) -> Iterator[EntryPoint]:
+    cfg = configparser.ConfigParser()
+    cfg.read(setup_cfg_path)
+    raw_data = cfg.get("options.entry_points", group_name, fallback="").strip()
+    if not raw_data:
+        return
+    data = {
+        k.strip(): v.strip()
+        for k, v in (line.split("=", maxsplit=1) for line in raw_data.splitlines())
+    }
+    for name, ref in data.items():
+        yield EntryPoint(name=name, value=ref, group=group_name)

ai/backend/plugin/py.typed

@@ -0,0 +1 @@
+placeholder

backend_ai_plugin-25.15.2.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: backend.ai-plugin
+Version: 25.15.2
+Summary: Backend.AI Plugin Subsystem
+Home-page: https://github.com/lablup/backend.ai
+Author: Lablup Inc. and contributors
+License: MIT
+Project-URL: Documentation, https://docs.backend.ai/
+Project-URL: Source, https://github.com/lablup/backend.ai
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.13,<3.14
+Description-Content-Type: text/markdown
+Requires-Dist: backend.ai-common==25.15.2
+Requires-Dist: backend.ai-logging==25.15.2
+Requires-Dist: click~=8.1.7
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: tabulate~=0.8.9
+Requires-Dist: types-colorama
+Requires-Dist: types-tabulate
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Backend.AI Plugin Subsystem
+===========================
+
+Package Structure
+-----------------
+
+* `ai.backend.plugin`: Abstract types for plugins and a common base plugin set

backend_ai_plugin-25.15.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+ai/backend/plugin/VERSION,sha256=Aig_MLMa-68Pxwp0ahtE-G2J7qgFOiLM1FhHGUYlRTM,8
+ai/backend/plugin/__init__.py,sha256=HKBIEWtrpEk2KY3fB3Xb72N0xz5zoYUyn2HfZ75bTsc,96
+ai/backend/plugin/cli.py,sha256=7SLUJy-8uPd_tSBOEZPYw1566QwrJJmCngoVyqrPAWE,5182
+ai/backend/plugin/entrypoint.py,sha256=lFqz-QNcWfYBlFoDTGEU5sY0CgYD0NWEHhhtmXs4840,12083
+ai/backend/plugin/py.typed,sha256=L3M0nPxGMCVTGcbI38G0aomWrOnRTY4HVjsWWRWRjsI,12
+backend_ai_plugin-25.15.2.dist-info/METADATA,sha256=victY9slizzDnh60RYgegyYCsEinpki5U1LbLbk39xo,1528
+backend_ai_plugin-25.15.2.dist-info/WHEEL,sha256=ooBFpIzZCPdw3uqIQsOo4qqbA4ZRPxHnOH7peeONza0,91
+backend_ai_plugin-25.15.2.dist-info/entry_points.txt,sha256=XxdR8AJRnWYCT-BgkqvFySRw_WjL0r9M43fRAVszaqY,56
+backend_ai_plugin-25.15.2.dist-info/namespace_packages.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+backend_ai_plugin-25.15.2.dist-info/top_level.txt,sha256=TJAp5TUfTUztZSUatbygths7CWRrFfnOMCtZ-DIcw6c,3
+backend_ai_plugin-25.15.2.dist-info/RECORD,,

backend_ai_plugin-25.15.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

backend_ai_plugin-25.15.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[backendai_cli_v10]
+plugin = ai.backend.plugin.cli:main

backend_ai_plugin-25.15.2.dist-info/namespace_packages.txt

@@ -0,0 +1 @@
+

backend_ai_plugin-25.15.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+ai