backend.ai-plugin 24.3.9b1__py3-none-any.whl → 25.15.5__py3-none-any.whl

ai/backend/plugin/VERSION

@@ -1 +1 @@
-24.03.9b1
+25.15.5

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

@@ -1,9 +1,13 @@
+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
@@ -19,9 +23,10 @@ def scan_entrypoints(
     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_plugin_checkouts(group_name),
         scan_entrypoint_from_package_metadata(group_name),
     ):
         if allowlist is not None and not match_plugin_list(entrypoint.value, allowlist):
@@ -62,6 +67,8 @@ def match_plugin_list(entry_path: str, plugin_list: set[str]) -> bool:
 
 
 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)
 
 
@@ -70,27 +77,82 @@ _default_glob_excluded_patterns = [
     "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]) -> Iterator[Path]:
-    q: collections.deque[Path] = collections.deque()
-    q.append(base_path)
+
+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 = q.pop()
-        assert search_path.is_dir()
+        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 search_path.name == "__pycache__":
+                if item.name == "__pycache__":
                     continue
-                if search_path.name.startswith("."):
+                if item.name.startswith("."):
                     continue
-                if any(search_path.match(pattern) for pattern in excluded_patterns):
+                if any(item.match(pattern) for pattern in excluded_patterns):
                     continue
-                q.append(item)
+
+                # 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 item
+                    # 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]:
@@ -100,20 +162,36 @@ def scan_entrypoint_from_buildscript(group_name: str) -> Iterator[EntryPoint]:
     log.debug(
         "scan_entrypoint_from_buildscript(%r): Namespace path: %s", group_name, ai_backend_ns_path
     )
-    for buildscript_path in _glob(ai_backend_ns_path, "BUILD", _default_glob_excluded_patterns):
+    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
-    # Override with the entrypoints found in the current source directories,
-    try:
-        build_root = find_build_root()
-    except ValueError:
-        pass
+    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:
-        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):
-            for entrypoint in extract_entrypoints_from_buildscript(group_name, buildscript_path):
-                entrypoints[entrypoint.name] = entrypoint
+        log.debug(
+            "scan_entrypoint_from_buildscript(%r): skipping 'src' when executed inside the SCIE environment",
+            group_name,
+        )
     yield from entrypoints.values()
 
 
@@ -143,6 +221,20 @@ def scan_entrypoint_from_plugin_checkouts(group_name: str) -> Iterator[EntryPoin
     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)

{backend.ai_plugin-24.3.9b1.dist-info → backend_ai_plugin-25.15.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: backend.ai-plugin
-Version: 24.3.9b1
+Version: 25.15.5
 Summary: Backend.AI Plugin Subsystem
 Home-page: https://github.com/lablup/backend.ai
 Author: Lablup Inc. and contributors
@@ -15,11 +15,28 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Environment :: No Input/Output (Daemon)
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.13
 Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.12,<3.13
+Requires-Python: >=3.13,<3.14
 Description-Content-Type: text/markdown
+Requires-Dist: backend.ai-common==25.15.5
+Requires-Dist: backend.ai-logging==25.15.5
+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
 ===========================

backend_ai_plugin-25.15.5.dist-info/RECORD

@@ -0,0 +1,11 @@
+ai/backend/plugin/VERSION,sha256=Q0grptxKHmGs0zbrjO9Pd6vBscOXL2Wus3WF9nw9xXI,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.5.dist-info/METADATA,sha256=T3J6Ia6qIrr4bjQi-S2ZFUq6sxQXAG5nBcFL35uSROs,1528
+backend_ai_plugin-25.15.5.dist-info/WHEEL,sha256=ooBFpIzZCPdw3uqIQsOo4qqbA4ZRPxHnOH7peeONza0,91
+backend_ai_plugin-25.15.5.dist-info/entry_points.txt,sha256=XxdR8AJRnWYCT-BgkqvFySRw_WjL0r9M43fRAVszaqY,56
+backend_ai_plugin-25.15.5.dist-info/namespace_packages.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+backend_ai_plugin-25.15.5.dist-info/top_level.txt,sha256=TJAp5TUfTUztZSUatbygths7CWRrFfnOMCtZ-DIcw6c,3
+backend_ai_plugin-25.15.5.dist-info/RECORD,,

{backend.ai_plugin-24.3.9b1.dist-info → backend_ai_plugin-25.15.5.dist-info}/WHEEL

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

backend_ai_plugin-25.15.5.dist-info/entry_points.txt

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

backend.ai_plugin-24.3.9b1.dist-info/RECORD

@@ -1,9 +0,0 @@
-ai/backend/plugin/VERSION,sha256=nbYJZmVl6PFYyLMBzO0xWpgVCdtDsJkASxzXmRELNaM,10
-ai/backend/plugin/__init__.py,sha256=HKBIEWtrpEk2KY3fB3Xb72N0xz5zoYUyn2HfZ75bTsc,96
-ai/backend/plugin/entrypoint.py,sha256=7VU_dl8QnrR7n2kTRsmdy0VCIqwtrUcrTMti2hWM6xk,8172
-ai/backend/plugin/py.typed,sha256=L3M0nPxGMCVTGcbI38G0aomWrOnRTY4HVjsWWRWRjsI,12
-backend.ai_plugin-24.3.9b1.dist-info/METADATA,sha256=ZvGGReukg1pHCSdFxLbDdbQHyhqA1N_vsRf4ruyhj-8,1068
-backend.ai_plugin-24.3.9b1.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
-backend.ai_plugin-24.3.9b1.dist-info/namespace_packages.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-backend.ai_plugin-24.3.9b1.dist-info/top_level.txt,sha256=TJAp5TUfTUztZSUatbygths7CWRrFfnOMCtZ-DIcw6c,3
-backend.ai_plugin-24.3.9b1.dist-info/RECORD,,