nemo-platform-plugin 0.1.0__py3-none-any.whl

nemo_platform/cli/core/lazy_load.py

@@ -0,0 +1,187 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from pkgutil import resolve_name
+from typing import Any, Callable, Sequence
+
+import click
+from click import Command
+from typer import Typer
+from typer.main import get_command as typer_get_command
+
+from nemo_platform.cli.core.help_formatter import NmpGroup
+from nemo_platform.cli.manifest import TopLevelEntry
+
+
+def attach_lazy_entries(
+    callback: Callable[..., Any],
+    entries: Sequence[TopLevelEntry],
+) -> None:
+    """Attach metadata-only child entries to a group callback.
+
+    The root callback carries the top-level manifest so `ManifestBackedNmpGroup`
+    can render root help without materializing every child command first.
+    """
+    callback.__nmp_lazy_entries__ = tuple(entries)
+
+
+class ManifestBackedNmpGroup(NmpGroup):
+    """Group that renders lazy child metadata and loads real children on demand."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._lazy_entries: dict[str, TopLevelEntry] = {}
+        # The callback is the stable place where the root app keeps its lazy
+        # child manifest. Group help reads this metadata, and subcommand lookup
+        # loads just the requested child command.
+        callback = getattr(self, "callback", None)
+        lazy_entries = getattr(callback, "__nmp_lazy_entries__", ())
+        for entry in lazy_entries:
+            self._lazy_entries[entry.name] = entry
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        names = list(self.commands)
+        for name in self._lazy_entries:
+            if name not in self.commands:
+                names.append(name)
+        return names
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> Command | None:
+        command = super().get_command(ctx, cmd_name)
+        if command is not None:
+            return command
+
+        entry = self._lazy_entries.get(cmd_name)
+        if entry is None:
+            return None
+
+        loader = build_lazy_loader(entry)
+        command = self._patch_command(loader())
+        command.name = cmd_name
+        command.hidden = command.hidden or entry.hidden
+        panel = getattr(command, "rich_help_panel", None)
+        if panel is None or type(panel).__name__ == "DefaultPlaceholder":
+            command.rich_help_panel = entry.panel
+        self.commands[cmd_name] = command
+        return command
+
+
+def build_lazy_loader(entry: TopLevelEntry) -> Callable[[], click.Command]:
+    if entry.source == "plugin":
+        return lazy_plugin_loader(entry.name, entry.import_path)
+    if entry.kind == "group":
+        return lazy_group_loader(entry.import_path)
+    return lazy_command_loader(entry.import_path)
+
+
+def lazy_plugin_loader(plugin_name: str, import_path: str) -> Callable[[], click.Command]:
+    """Resolve a plugin CLI from its entry-point import path when needed."""
+
+    def _plugin_placeholder_command(help_text: str) -> click.Command:
+        return click.Group(name=plugin_name, help=help_text)
+
+    def _load_plugin_cli() -> click.Command:
+        from nemo_platform.cli.app import (
+            _add_plugin_function_commands,
+            _add_plugin_job_commands,
+            _discover_plugin_function_entry_points,
+            _discover_plugin_job_entry_points,
+        )
+
+        try:
+            cli_cls = resolve_name(import_path)
+            cli_obj = cli_cls()
+            plugin_app = cli_obj.get_cli()
+        except Exception:
+            return _plugin_placeholder_command(f"Plugin commands for {plugin_name} are unavailable.")
+
+        job_entry_points = _discover_plugin_job_entry_points()
+        if job_entry_points is not None:
+            plugin_jobs = {}
+            for job_name, job_entry_point in job_entry_points.items():
+                if not job_name.startswith(f"{plugin_name}."):
+                    continue
+                try:
+                    plugin_jobs[job_name] = job_entry_point.load()
+                except Exception:
+                    continue
+            if plugin_jobs:
+                _add_plugin_job_commands(plugin_app, plugin_jobs, cli=cli_obj)
+
+        # Functions live alongside jobs at the plugin level; mirror the
+        # same per-plugin filtering so a multi-plugin install only sees
+        # this plugin's functions in the resolved CLI tree.
+        function_entry_points = _discover_plugin_function_entry_points()
+        if function_entry_points is not None:
+            plugin_functions = {}
+            for fn_name, fn_entry_point in function_entry_points.items():
+                if not fn_name.startswith(f"{plugin_name}."):
+                    continue
+                try:
+                    plugin_functions[fn_name] = fn_entry_point.load()
+                except Exception:
+                    continue
+            if plugin_functions:
+                _add_plugin_function_commands(plugin_app, plugin_functions, cli=cli_obj)
+
+        try:
+            return typer_get_command(plugin_app)
+        except RuntimeError:
+            return _plugin_placeholder_command(plugin_app.info.help or f"Plugin commands for {plugin_name}.")
+
+    return _load_plugin_cli
+
+
+def lazy_group_loader(import_path: str) -> Callable[[], click.Command]:
+    """Resolve a Typer app from ``module:attribute`` when needed."""
+
+    def _load_group() -> click.Command:
+        nested_name = "__lazy_group__"
+        temp_app = Typer()
+        temp_app.add_typer(resolve_name(import_path), name=nested_name)
+        root_command = typer_get_command(temp_app)
+        nested_command = root_command.get_command(click.Context(root_command), nested_name)
+        if nested_command is None:
+            raise click.ClickException(f"Failed to build nested CLI group for {import_path!r}")
+        return nested_command
+
+    def _lazy_loader() -> click.Command:
+        try:
+            return _load_group()
+        except (ModuleNotFoundError, AttributeError) as exc:
+            raise click.ClickException(f"Failed to load CLI group {import_path!r}: {exc}") from exc
+
+    return _lazy_loader
+
+
+def lazy_command_loader(import_path: str) -> Callable[[], click.Command]:
+    """Resolve a top-level command from ``module:attribute`` when needed."""
+
+    def _load_command() -> click.Command:
+        holder_name = "__lazy_command_holder__"
+        command = resolve_name(import_path)
+        holder_app = Typer()
+        holder_app.command()(command)
+        temp_app = Typer()
+        temp_app.add_typer(holder_app, name=holder_name)
+        root_command = typer_get_command(temp_app)
+        holder_command = root_command.get_command(click.Context(root_command), holder_name)
+        if holder_command is None or not isinstance(holder_command, click.Group):
+            raise click.ClickException(f"Failed to build nested CLI command holder for {import_path!r}")
+        nested_commands = list(holder_command.commands.values())
+        if len(nested_commands) != 1:
+            raise click.ClickException(f"Failed to build nested CLI command for {import_path!r}")
+        nested_command = nested_commands[0]
+        if nested_command is None:
+            raise click.ClickException(f"Failed to build nested CLI command for {import_path!r}")
+        return nested_command
+
+    def _lazy_loader() -> click.Command:
+        try:
+            return _load_command()
+        except (ModuleNotFoundError, AttributeError) as exc:
+            raise click.ClickException(f"Failed to load CLI command {import_path!r}: {exc}") from exc
+
+    return _lazy_loader

nemo_platform/cli/core/logging.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+
+
+def configure_logging(verbosity: int) -> None:
+    """Configure logging based on verbosity level."""
+    if verbosity > 0:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%H:%M:%S",
+            force=True,
+        )
+        logging.getLogger("httpx").setLevel(logging.DEBUG)
+        logging.getLogger("httpcore").setLevel(logging.DEBUG)
+        logger = logging.getLogger("nemo_platform.cli")
+        logger.setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+    else:
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+        logging.getLogger("httpcore").setLevel(logging.WARNING)
+        logging.getLogger("nemo_platform.cli").setLevel(logging.WARNING)

nemo_platform/cli/core/pagination.py

@@ -0,0 +1,255 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pagination utilities for the NeMo CLI."""
+
+from __future__ import annotations
+
+import logging
+import typing
+from enum import Enum
+from typing import Any, Callable
+
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from nemo_platform.cli.core.help_formatter import add_warning
+
+if typing.TYPE_CHECKING:
+    from nemo_platform.pagination import SyncDefaultPagination, SyncLogsPagination
+
+logger = logging.getLogger(__name__)
+
+
+class PaginationType(str, Enum):
+    """Types of pagination supported by the API."""
+
+    PAGE_NUMBER = "page_number"  # Uses page/page_size params (default_pagination)
+    CURSOR = "cursor"  # Uses limit/page_cursor params (logs_pagination)
+    NOT_PAGINATED = "not_paginated"  # List operation without pagination support
+
+
+class AllPagesResponse:
+    """
+    A response object that mimics a single-page response but contains all items.
+
+    This ensures --all-pages returns the same structure as a single page response.
+    Used for page-number based pagination which has total_pages and total_results.
+    """
+
+    def __init__(self, data: list[Any], total_items: int, total_pages: int, page_size: int | None = None):
+        self.data = data
+        self.sort = None
+
+        # Create pagination info for all items
+        self.pagination = type(
+            "obj",
+            (object,),
+            {
+                "page": 1,
+                "page_size": page_size or len(data),
+                "current_page_size": len(data),
+                "total_pages": 1,  # All data is now in one "page"
+                "total_results": total_items,
+            },
+        )()
+
+    def model_dump(self, mode: str = "json") -> dict[str, Any]:
+        """Make this compatible with Pydantic's model_dump."""
+        # Convert data items to dicts if they're Pydantic models
+        serialized_data = []
+        for item in self.data:
+            if hasattr(item, "model_dump"):
+                serialized_data.append(item.model_dump(mode=mode))
+            elif isinstance(item, dict):
+                serialized_data.append(item)
+            else:
+                serialized_data.append(item)
+
+        return {
+            "data": serialized_data,
+            "sort": self.sort,
+            "pagination": {
+                "page": self.pagination.page,
+                "page_size": self.pagination.page_size,
+                "current_page_size": self.pagination.current_page_size,
+                "total_pages": self.pagination.total_pages,
+                "total_results": self.pagination.total_results,
+            },
+        }
+
+
+class AllCursorPagesResponse:
+    """
+    A response object for cursor-based pagination results.
+
+    Cursor-based pagination doesn't have total_pages or total_results,
+    so this response only contains the collected data and item count.
+    """
+
+    def __init__(self, data: list[Any], limit: int | None = None):
+        self.data = data
+        self.next_page = None  # All pages fetched, no next page
+
+        # Store the original limit for reference
+        self._limit = limit
+
+    def model_dump(self, mode: str = "json") -> dict[str, Any]:
+        """Make this compatible with Pydantic's model_dump."""
+        # Convert data items to dicts if they're Pydantic models
+        serialized_data = []
+        for item in self.data:
+            if hasattr(item, "model_dump"):
+                serialized_data.append(item.model_dump(mode=mode))
+            elif isinstance(item, dict):
+                serialized_data.append(item)
+            else:
+                serialized_data.append(item)
+
+        return {
+            "data": serialized_data,
+            "next_page": self.next_page,
+        }
+
+
+def _fetch_all_pages_page_number(
+    list_method: Callable[..., SyncDefaultPagination[Any]],
+    progress: Progress,
+    task: Any,
+    path_args: tuple[Any, ...],
+    body_args: dict[str, Any],
+) -> AllPagesResponse:
+    """
+    Fetch all pages using page-number based pagination.
+
+    This is used for endpoints with `default_pagination` in the stainless config.
+    """
+    all_items: list[Any] = []
+    page_num = 1
+    total_pages_count = 0
+    total_results = 0
+    original_page_size = None
+
+    # Fetch the first page
+    try:
+        response = list_method(*path_args, **body_args)
+    except Exception as e:
+        progress.stop()
+        raise e
+
+    if (total_pages := response.pagination.total_pages) is not None:
+        progress.update(task, total=total_pages)
+        total_pages_count = total_pages
+
+    # TODO: quiet logging context manager
+    logging.getLogger().setLevel(logging.CRITICAL)
+    for page in response.iter_pages():
+        page_num = page.pagination.page
+
+        for item in page.data:
+            all_items.append(item)
+
+        progress.update(
+            task, completed=page_num, description=f"Fetching pages... (page {page_num + 1}/{total_pages_count})"
+        )
+
+    return AllPagesResponse(
+        data=all_items,
+        total_items=total_results or len(all_items),
+        total_pages=total_pages_count,
+        page_size=original_page_size,
+    )
+
+
+def _fetch_all_pages_cursor(
+    list_method: Callable[..., SyncLogsPagination],
+    progress: Progress,
+    task: Any,
+    path_args: tuple[Any, ...],
+    body_args: dict[str, Any],
+) -> AllCursorPagesResponse:
+    """
+    Fetch all pages using cursor-based pagination.
+
+    This is used for endpoints with `logs_pagination` in the stainless config.
+    """
+    all_items: list[Any] = []
+    page_num = 1
+
+    # Fetch the first page
+    try:
+        response = list_method(*path_args, **body_args)
+    except Exception as e:
+        progress.stop()
+        raise e
+
+    # TODO: quiet logging context manager
+    logging.getLogger().setLevel(logging.CRITICAL)
+    for page in response.iter_pages():
+        page_num += 1
+
+        for item in page.data:
+            all_items.append(item)
+
+        progress.update(task, completed=page_num, description=f"Fetching pages... (page {page_num + 1})")
+
+    return AllCursorPagesResponse(
+        data=all_items,
+        limit=body_args.get("limit", None),
+    )
+
+
+def fetch_all_pages(
+    list_method: Callable[..., Any],
+    path_args: tuple[Any, ...] = (),
+    body_args: dict[str, Any] | None = None,
+    show_progress: bool = True,
+    pagination_type: PaginationType = PaginationType.PAGE_NUMBER,
+) -> AllPagesResponse | AllCursorPagesResponse:
+    """
+    Fetch all pages from a paginated endpoint.
+
+    Args:
+        list_method: The SDK list method to call (e.g., client.namespaces.list)
+        path_args: Positional arguments to pass to the list method (e.g., job_id)
+        body_args: Keyword arguments to pass to the list method (e.g., filter, search)
+        show_progress: Whether to show a progress indicator
+        pagination_type: Type of pagination - PAGE_NUMBER (default) or CURSOR
+
+    Returns:
+        AllPagesResponse for page-number pagination, AllCursorPagesResponse for cursor pagination
+    """
+    if body_args is None:
+        body_args = {}
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        transient=True,
+        disable=not show_progress,
+    ) as progress:
+        task = progress.add_task("Fetching pages...", total=None)
+
+        if pagination_type == PaginationType.CURSOR:
+            return _fetch_all_pages_cursor(list_method, progress, task, path_args, body_args)
+        else:
+            return _fetch_all_pages_page_number(list_method, progress, task, path_args, body_args)
+
+
+def warn_if_more_pages(
+    response: Any,
+    pagination_type: PaginationType,
+) -> None:
+    """
+    Warn the user if there are more pages available.
+
+    Args:
+        response: The response object from the list method
+        pagination_type: Type of pagination - PAGE_NUMBER (default) or CURSOR
+    """
+    if pagination_type == PaginationType.NOT_PAGINATED:
+        return  # No pagination, no warning needed
+    elif pagination_type == PaginationType.CURSOR:
+        if getattr(response, "next_page", None):
+            add_warning("More pages of results are available! Use --all-pages to fetch all results.")
+    elif hasattr(response, "pagination") and getattr(response.pagination, "total_pages", 1) > 1:
+        add_warning("More pages of results are available! Use --all-pages to fetch all results.")

nemo_platform/cli/core/stdin_utils.py

@@ -0,0 +1,233 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Utilities for reading input from stdin."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import yaml
+from click import UsageError
+
+
+def is_stdin_available() -> bool:
+    """
+    Check if stdin has data available (i.e., data is being piped in).
+
+    Returns:
+        True if stdin is not a TTY (data is being piped), False otherwise
+    """
+    return not sys.stdin.isatty()
+
+
+def read_data_from_stdin() -> dict[str, Any]:
+    """
+    Read and parse JSON from stdin.
+
+    Returns:
+        Parsed JSON data as a dictionary
+
+    Raises:
+        ValueError: If stdin is empty or contains invalid JSON
+    """
+    if not is_stdin_available():
+        raise ValueError("No input available on stdin")
+
+    stdin_data = sys.stdin.read().strip()
+
+    if not stdin_data:
+        raise ValueError("Stdin is empty")
+
+    try:
+        data = yaml.safe_load(stdin_data)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid data in stdin: {e}")
+
+    if not isinstance(data, dict):
+        raise ValueError("JSON input must be an object/dictionary")
+
+    return data
+
+
+def merge_stdin_with_options(stdin_data: dict[str, Any], **cli_options: Any) -> dict[str, Any]:
+    """
+    Merge stdin data with CLI options.
+
+    CLI options take precedence over stdin data.
+
+    Args:
+        stdin_data: Data parsed from stdin
+        **cli_options: Options provided via CLI flags
+
+    Returns:
+        Merged dictionary with CLI options taking precedence
+    """
+    # Start with stdin data
+    result = dict(stdin_data)
+
+    # Override with CLI options (only non-None values)
+    for key, value in cli_options.items():
+        if value is not None:
+            result[key] = value
+
+    return result
+
+
+def read_data_input_with_flags(
+    input_file: str | None = None,
+    input_data: str | None = None,
+) -> dict[str, Any]:
+    """
+    Read data from explicit --input-file or --input-json flags.
+
+    Args:
+        input_file: Path to data file, or "-" for stdin
+        input_data: Inline data (JSON or YAML string)
+
+    Returns:
+        Parsed data as dictionary
+
+    Raises:
+        ValueError: If both or neither flags are provided, or if input is invalid
+    """
+    # Validate mutually exclusive flags
+    if input_file and input_data:
+        raise ValueError("Cannot use both --input-file and --input-data. Choose one.")
+
+    if not input_file and not input_data:
+        raise ValueError("Must provide input via --input-file or --input-data")
+
+    # Handle --input-file
+    if input_file:
+        # Handle stdin (dash convention)
+        if input_file == "-":
+            if not is_stdin_available():
+                raise ValueError("No data available on stdin")
+            return read_data_from_stdin()
+
+        # Handle file path
+        try:
+            # Support both relative and absolute paths
+            if not os.path.isabs(input_file):
+                input_file = os.path.abspath(input_file)
+
+            with open(input_file) as f:
+                data = yaml.safe_load(f)
+
+            if not isinstance(data, dict):
+                raise ValueError(f"File {input_file} must contain an object (in the form '{{field: value, ...}}')")
+
+            return data
+        except FileNotFoundError:
+            raise ValueError(f"File not found: {input_file}")
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid data in file {input_file}: {e}")
+        except Exception as e:
+            raise ValueError(f"Error reading file {input_file}: {e}")
+
+    # Handle --input-data
+    if input_data:
+        data = read_payload("input-data", input_data)
+        if not isinstance(data, dict):
+            raise ValueError("JSON input must be an object (in the form '{field: value, ...}').")
+        return data
+
+    # Should never reach here due to validation above
+    raise ValueError("No input provided")
+
+
+def validate_required_fields(
+    payload: dict[str, Any],
+    required_fields: list[str],
+    command_name: str = "this command",
+    field_help: dict[str, str] | None = None,
+) -> None:
+    """
+    Validate that all required fields are present in the merged payload.
+
+    Args:
+        payload: The merged payload (JSON input + CLI overrides)
+        required_fields: List of field names that must be present
+        command_name: Name of the command for error messages
+        field_help: Optional dict mapping field names to help text
+
+    Raises:
+        MissingRequiredFieldsError: If any required field is missing
+    """
+    from nemo_platform.cli.core.errors import MissingRequiredFieldsError
+
+    missing = [f for f in required_fields if f not in payload or payload[f] is None]
+
+    if missing:
+        raise MissingRequiredFieldsError(missing, command_name, field_help)
+
+
+def read_payload(field_name: str, field_value: str) -> Any:
+    """
+    Read payload for a specific field, supporting JSON and YAML strings.
+
+    Args:
+        field_name: Name of the field (for error messages)
+        field_value: Value provided via CLI flag (JSON string or file path)
+    Returns:
+        Parsed value (could be dict, list, etc.)
+    """
+
+    try:
+        return yaml.safe_load(field_value)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid data for field '{field_name}': {e}")
+
+
+def read_secret_from_file(path: str, option_name: str) -> str:
+    if path == "-":
+        if not is_stdin_available():
+            raise UsageError(f"No input provided on stdin, but required for '--{option_name} -'")
+        data = sys.stdin.read().strip()
+    else:
+        try:
+            with open(path) as f:
+                data = f.read().strip()
+        except FileNotFoundError as e:
+            raise UsageError(f"File not found: {path}") from e
+        except PermissionError as e:
+            raise UsageError(f"Permission denied reading file: {path}") from e
+
+    if not data:
+        raise UsageError(
+            "Secret value cannot be empty. Provide non-empty content via --from-file "
+            "(e.g. a file path or '-' to read from stdin or use --value for inline secret)."
+        )
+    return data
+
+
+def resolve_secret_value(
+    from_file: str | None,
+    value: str | None,
+    *,
+    required: bool = False,
+    command_name: str = "this command",
+) -> str | None:
+    """Resolve secret value from --from-file or --value.
+
+    Use required=True for create (exactly one source required).
+    Use required=False for update (optional; returns None if neither given).
+    """
+    if from_file is not None and value is not None:
+        raise UsageError("Cannot use both --from-file and --value. Choose one.")
+    if from_file is None and value is None:
+        if required:
+            raise UsageError(
+                f"Provide secret value via --value or --from-file for {command_name}. "
+                'Example: nemo secrets create my-secret --value "abc123"'
+            )
+        return None
+    if from_file is not None:
+        return read_secret_from_file(from_file.strip(), "from-file")
+    stripped = (value or "").strip()
+    if not stripped:
+        raise UsageError("Secret value cannot be empty. Provide non-empty content via --value or --from-file.")
+    return stripped