lightning-sdk 2025.11.13.post0__py3-none-any.whl

lightning_sdk/base_studio.py

@@ -0,0 +1,123 @@
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+from lightning_sdk.api.base_studio_api import BaseStudioApi
+from lightning_sdk.api.user_api import UserApi
+from lightning_sdk.lightning_cloud.openapi.models.v1_cloud_space_environment_type import V1CloudSpaceEnvironmentType
+from lightning_sdk.organization import Organization
+from lightning_sdk.teamspace import Teamspace
+from lightning_sdk.user import User
+from lightning_sdk.utils.resolve import _resolve_teamspace
+
+
+@dataclass
+class BaseStudioInfo:
+    id: str
+    name: str
+    managed_id: str
+    description: str
+    creator: str
+    enabled: bool
+
+
+class BaseStudio:
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        teamspace: Optional[Union[str, Teamspace]] = None,
+        org: Optional[Union[str, Organization]] = None,
+        user: Optional[Union[str, User]] = None,
+    ) -> None:
+        """Initializes the BaseStudio instance with organization and user information.
+
+        Args:
+            org (Optional[Union[str, Organization]]): The organization for the base studio. If not provided,
+                                                      it will be resolved through the authentication process.
+            user (Optional[Union[str, User]]): The user for the base studio. If not provided, it will be resolved
+                                               through the authentication process.
+
+        Raises:
+            ConnectionError: If there is an issue with the authentication process.
+        """
+        self._teamspace = None
+
+        _teamspace = _resolve_teamspace(teamspace=teamspace, org=org, user=user)
+        if _teamspace is None:
+            raise ValueError("Couldn't resolve teamspace from the provided name, org, or user")
+
+        self._teamspace = _teamspace
+
+        # self._auth = login.Auth()
+        # self._user = None
+
+        # try:
+        #     self._auth.authenticate()
+        #     if user is None:
+        #         self._user = User(name=UserApi()._get_user_by_id(self._auth.user_id).username)
+        # except ConnectionError as e:
+        #     raise e
+
+        # self._user = _resolve_user(self._user or user)
+        # self._org = _resolve_org(org)
+
+        self._base_studio_api = BaseStudioApi()
+
+        if name is not None:
+            org_id = self._teamspace._org.id if self._teamspace._org is not None else None
+            base_studio = self._base_studio_api.get_base_studio(name, org_id)
+
+            if base_studio is None:
+                raise ValueError(f"Base studio with name {name} does not exist")
+            self._base_studio = base_studio
+
+    def update(
+        self,
+        name: Optional[str] = None,
+        allowed_machines: Optional[List[str]] = None,
+        default_machine: Optional[str] = None,
+        disabled: Optional[bool] = None,
+        environment_type: Optional[V1CloudSpaceEnvironmentType] = None,
+        machine_image_version: Optional[str] = None,
+        setup_script_text: Optional[str] = None,
+    ) -> None:
+        org_id = self._teamspace._org.id if self._teamspace._org is not None else None
+        # TODO: if not in an org, can't update them
+        self._base_studio = self._base_studio_api.update_base_studio(
+            self._base_studio.id,
+            org_id,
+            name=name,
+            allowed_machines=allowed_machines,
+            default_machine=default_machine,
+            environment_type=environment_type,
+            machine_image_version=machine_image_version,
+            setup_script_text=setup_script_text,
+            disabled=disabled,
+        )
+
+    def list(self, include_disabled: bool = False) -> List[BaseStudioInfo]:
+        """List all base studios in the organization.
+
+        Args:
+            managed: Whether to filter for managed base studios.
+            include_disabled: Whether to include disabled base studios in the results.
+
+        Returns:
+            List[BaseStudioInfo]: A list of base studio templates.
+        """
+        org_id = self._teamspace._org.id if self._teamspace._org is not None else None
+        templates = self._base_studio_api.get_all_base_studios(org_id).templates
+
+        return [
+            BaseStudioInfo(
+                id=template.id,
+                name=template.name,
+                managed_id=template.managed_id,
+                description=template.description,
+                creator="⚡ Lightning AI"
+                if template.managed_id
+                else UserApi()._get_user_by_id(template.user_id).username,
+                enabled=not template.disabled,
+            )
+            for template in templates
+            if include_disabled or not template.disabled
+        ]

lightning_sdk/cli/__init__.py

@@ -0,0 +1 @@
+"""Lightning SDK CLI module."""

lightning_sdk/cli/base_studio/__init__.py

@@ -0,0 +1,10 @@
+"""Base Studio CLI commands."""
+
+import click
+
+
+def register_commands(group: click.Group) -> None:
+    """Register base studio commands with the given group."""
+    from lightning_sdk.cli.base_studio.list import list_base_studios
+
+    group.add_command(list_base_studios)

lightning_sdk/cli/base_studio/list.py

@@ -0,0 +1,43 @@
+"""Base Studio list command."""
+
+import click
+from rich.table import Table
+
+from lightning_sdk.base_studio import BaseStudio
+from lightning_sdk.cli.utils.richt_print import rich_to_str
+
+
+@click.command("list")
+@click.option("--include-disabled", help="Include disabled Base Studios in the list.", is_flag=True)
+def list_base_studios(include_disabled: bool) -> None:
+    """List Base Studios in an org.
+
+    Example:
+        lightning base-studio list
+
+    """
+    return list_impl(include_disabled=include_disabled)
+
+
+def list_impl(include_disabled: bool) -> None:
+    base_studio_cls = BaseStudio()
+    base_studios = base_studio_cls.list(include_disabled=include_disabled)
+
+    table = Table(
+        pad_edge=True,
+    )
+
+    table.add_column("Name")
+    table.add_column("Description")
+    table.add_column("Creator")
+    table.add_column("Enabled")
+
+    for base_studio in base_studios:
+        table.add_row(
+            base_studio.name.lower().replace(" ", "-"),
+            base_studio.description or "",
+            base_studio.creator,
+            "Yes" if base_studio.enabled else "No",
+        )
+
+    click.echo(rich_to_str(table), color=True)

lightning_sdk/cli/config/__init__.py

@@ -0,0 +1,14 @@
+"""Config CLI commands."""
+
+import click
+
+
+def register_commands(group: click.Group) -> None:
+    """Register config commands with the given group."""
+    from lightning_sdk.cli.config.get import get
+    from lightning_sdk.cli.config.set import set_value
+    from lightning_sdk.cli.config.show import show
+
+    group.add_command(get)
+    group.add_command(set_value)
+    group.add_command(show)

lightning_sdk/cli/config/get.py

@@ -0,0 +1,57 @@
+import click
+
+from lightning_sdk.utils.config import Config, DefaultConfigKeys
+
+
+@click.group("get")
+def get() -> None:
+    """Get configuration values."""
+
+
+@get.command("user")
+def get_user() -> None:
+    """Get the default user name from the config."""
+    config = Config()
+    user = config.get_value(DefaultConfigKeys.user)
+    click.echo(user)
+
+
+@get.command("org")
+def get_org() -> None:
+    """Get the default organization name from the config."""
+    config = Config()
+    org = config.get_value(DefaultConfigKeys.organization)
+    click.echo(org)
+
+
+@get.command("teamspace")
+def get_teamspace() -> None:
+    """Get the default teamspace name from the config."""
+    config = Config()
+    teamspace_name = config.get_value(DefaultConfigKeys.teamspace_name)
+    teamspace_owner = config.get_value(DefaultConfigKeys.teamspace_owner)
+    click.echo(f"{teamspace_owner}/{teamspace_name}")
+
+
+@get.command("studio")
+def get_studio() -> None:
+    """Get the default sutdio name from the config."""
+    config = Config()
+    studio = config.get_value(DefaultConfigKeys.studio)
+    click.echo(studio)
+
+
+@get.command("cloud-account")
+def get_cloud_account() -> None:
+    """Get the default cloud account name from the config."""
+    config = Config()
+    cloud_account = config.get_value(DefaultConfigKeys.cloud_account)
+    click.echo(cloud_account)
+
+
+@get.command("cloud-provider")
+def get_cloud_provider() -> None:
+    """Get the default cloud provider name from the config."""
+    config = Config()
+    cloud_provider = config.get_value(DefaultConfigKeys.cloud_provider)
+    click.echo(cloud_provider)

lightning_sdk/cli/config/set.py

@@ -0,0 +1,92 @@
+import click
+
+from lightning_sdk.cli.utils.save_to_config import save_teamspace_to_config
+from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
+from lightning_sdk.machine import CloudProvider
+from lightning_sdk.studio import Studio
+from lightning_sdk.utils.config import Config, DefaultConfigKeys
+from lightning_sdk.utils.resolve import _resolve_org, _resolve_user
+
+
+@click.group("set")
+def set_value() -> None:
+    """Set configuration values."""
+
+
+@set_value.command("user")
+@click.argument("user_name")
+def set_user(user_name: str) -> None:
+    """Set the default user name in the config."""
+    try:
+        _resolve_user(user_name)
+    except Exception:
+        # TODO: make this a generic CLI error
+        raise ValueError(f"Could not resolve user: '{user_name}'. Does the user exist?") from None
+
+    config = Config()
+    setattr(config, DefaultConfigKeys.user, user_name)
+
+
+@set_value.command("org")
+@click.argument("org_name")
+def set_org(org_name: str) -> None:
+    """Set the default organization name in the config."""
+    try:
+        _resolve_org(org_name)
+    except Exception:
+        # TODO: make this a generic CLI error
+        raise ValueError(f"Could not resolve organization: '{org_name}'. Does the organization exist?") from None
+
+    config = Config()
+    setattr(config, DefaultConfigKeys.organization, org_name)
+
+
+@set_value.command("studio")
+@click.argument("studio_name")
+def set_studio(studio_name: str) -> None:
+    """Set the default studio name in the config."""
+    try:
+        studio = Studio(studio_name)
+    except Exception:
+        # TODO: make this a generic CLI error
+        raise ValueError(f"Could not resolve studio: '{studio_name}'. Does the studio exist?") from None
+
+    config = Config()
+    setattr(config, DefaultConfigKeys.studio, studio.name)
+
+
+@set_value.command("teamspace")
+@click.argument("teamspace_name")
+def set_teamspace(teamspace_name: str) -> None:
+    """Set the default teamspace name in the config."""
+    menu = TeamspacesMenu()
+    teamspace_resolved = menu(teamspace=teamspace_name)
+
+    # explicit user action, so overwrite the config
+    save_teamspace_to_config(teamspace_resolved, overwrite=True)
+
+
+@set_value.command("cloud-account")
+@click.argument("cloud_account_name")
+def set_cloud_account(cloud_account_name: str) -> None:
+    """Set the default cloud account name in the config."""
+    config = Config()
+    setattr(config, DefaultConfigKeys.cloud_account, cloud_account_name)
+
+
+@set_value.command("cloud-provider")
+@click.argument("cloud_provider_name")
+def set_cloud_provider(cloud_provider_name: str) -> None:
+    """Set the default cloud provider name in the config."""
+    config = Config()
+
+    try:
+        cloud_provider = CloudProvider(cloud_provider_name)
+    except ValueError:
+        # TODO: make this a generic CLI error
+        raise ValueError(
+            f"Could not resolve cloud provider: '{cloud_provider_name}'. "
+            f"Supported values are: {', '.join(m.name for m in list(CloudProvider))}"
+        ) from None
+
+    setattr(config, DefaultConfigKeys.cloud_provider, cloud_provider.name)

lightning_sdk/cli/config/show.py

@@ -0,0 +1,9 @@
+import click
+
+from lightning_sdk.utils.config import Config
+
+
+@click.command("show")
+def show() -> None:
+    """Show configuration values."""
+    click.echo(Config())

lightning_sdk/cli/entrypoint.py

@@ -0,0 +1,110 @@
+"""New Lightning CLI entrypoint with organized command groups."""
+
+import os
+import sys
+
+import click
+
+from lightning_sdk import __version__
+from lightning_sdk.api.studio_api import _cloud_url
+
+# Import legacy groups directly from groups.py
+from lightning_sdk.cli.groups import (
+    base_studio,
+    config,
+    # job,
+    license,
+    # mmt,
+    studio,
+    vm,
+)
+from lightning_sdk.cli.utils import CustomHelpFormatter
+from lightning_sdk.cli.utils.logging import CommandLoggingGroup, logging_excepthook
+from lightning_sdk.lightning_cloud.login import Auth
+
+
+@click.group(
+    name="lightning",
+    help="Command line interface (CLI) to interact with/manage Lightning AI Studios.",
+    cls=CommandLoggingGroup,
+)
+@click.version_option(__version__, message="Lightning CLI version %(version)s")
+def main_cli() -> None:
+    sys.excepthook = logging_excepthook
+
+
+main_cli.context_class.formatter_class = CustomHelpFormatter
+
+
+@main_cli.command
+def login() -> None:
+    """Login to Lightning AI Studios."""
+    auth = Auth()
+    auth.clear()
+
+    try:
+        auth.authenticate()
+    except ConnectionError:
+        raise RuntimeError(f"Unable to connect to {_cloud_url()}. Please check your internet connection.") from None
+
+
+@main_cli.command
+def logout() -> None:
+    """Logout from Lightning AI Studios."""
+    auth = Auth()
+    auth.clear()
+
+
+# Add new command groups
+main_cli.add_command(config)
+# main_cli.add_command(job)
+# main_cli.add_command(mmt)
+main_cli.add_command(studio)
+main_cli.add_command(vm)
+main_cli.add_command(base_studio)
+main_cli.add_command(license)
+
+if os.environ.get("LIGHTNING_EXPERIMENTAL_CLI_ONLY", "0") != "1":
+    #### LEGACY COMMANDS ####
+    # these commands are currently supported for backwards compatibility, but will potentially be removed in the future.
+    # they've grown pretty wild and provide a very inconsistent UX.
+    from lightning_sdk.cli.legacy.ai_hub import aihub
+    from lightning_sdk.cli.legacy.configure import configure
+    from lightning_sdk.cli.legacy.connect import connect
+    from lightning_sdk.cli.legacy.create import create
+    from lightning_sdk.cli.legacy.delete import delete
+    from lightning_sdk.cli.legacy.deploy.serve import deploy
+    from lightning_sdk.cli.legacy.docker_cli import dockerize
+    from lightning_sdk.cli.legacy.download import download
+    from lightning_sdk.cli.legacy.generate import generate
+    from lightning_sdk.cli.legacy.inspection import inspect
+    from lightning_sdk.cli.legacy.list import list_cli
+    from lightning_sdk.cli.legacy.open import open as open_cmd
+    from lightning_sdk.cli.legacy.run import run
+    from lightning_sdk.cli.legacy.start import start
+    from lightning_sdk.cli.legacy.stop import stop
+    from lightning_sdk.cli.legacy.switch import switch
+    from lightning_sdk.cli.legacy.upload import upload
+
+    # Add old command groups
+    main_cli.add_command(aihub)
+    main_cli.add_command(configure)
+    main_cli.add_command(connect)
+    main_cli.add_command(create)
+    main_cli.add_command(delete)
+    main_cli.add_command(deploy)
+    main_cli.add_command(dockerize)
+    main_cli.add_command(download)
+    main_cli.add_command(generate)
+    main_cli.add_command(inspect)
+    main_cli.add_command(list_cli)
+    main_cli.add_command(open_cmd)
+    main_cli.add_command(run)
+    main_cli.add_command(start)
+    main_cli.add_command(stop)
+    main_cli.add_command(switch)
+    main_cli.add_command(upload)
+
+
+if __name__ == "__main__":
+    main_cli()

lightning_sdk/cli/groups.py

@@ -0,0 +1,56 @@
+"""CLI groups for organizing Lightning SDK commands."""
+
+import click
+
+from lightning_sdk.cli.base_studio import register_commands as register_base_studio_commands
+from lightning_sdk.cli.config import register_commands as register_config_commands
+from lightning_sdk.cli.job import register_commands as register_job_commands
+from lightning_sdk.cli.license import register_commands as register_license_commands
+from lightning_sdk.cli.mmt import register_commands as register_mmt_commands
+from lightning_sdk.cli.studio import register_commands as register_studio_commands
+from lightning_sdk.cli.vm import register_commands as register_vm_commands
+
+
+@click.group(name="studio")
+def studio() -> None:
+    """Manage Lightning AI Studios."""
+
+
+@click.group(name="job")
+def job() -> None:
+    """Manage Lightning AI Jobs."""
+
+
+@click.group(name="mmt")
+def mmt() -> None:
+    """Manage Lightning AI Multi-Machine Training (MMT)."""
+
+
+@click.group(name="config")
+def config() -> None:
+    """Manage Lightning SDK and CLI configuration."""
+
+
+@click.group(name="vm")
+def vm() -> None:
+    """Manage Lightning AI VMs."""
+
+
+@click.group(name="base-studio")
+def base_studio() -> None:
+    """Manage Lightning AI Base Studios."""
+
+
+@click.group(name="license")
+def license() -> None:  # noqa: A001
+    """Manage Lightning AI Product Licenses."""
+
+
+# Register config commands with the main config group
+register_job_commands(job)
+register_mmt_commands(mmt)
+register_studio_commands(studio)
+register_config_commands(config)
+register_vm_commands(vm)
+register_base_studio_commands(base_studio)
+register_license_commands(license)

lightning_sdk/cli/job/__init__.py

@@ -0,0 +1,7 @@
+"""Job CLI commands."""
+
+import click
+
+
+def register_commands(group: click.Group) -> None:
+    """Register job commands with the given group."""

lightning_sdk/cli/legacy/ai_hub.py

@@ -0,0 +1,65 @@
+from typing import Optional
+
+import click
+
+from lightning_sdk.ai_hub import AIHub
+
+
+@click.group(name="aihub")
+def aihub() -> None:
+    """Interact with Lightning Studio - AI Hub."""
+
+
+@aihub.command(name="api-info")
+@click.argument("api-id")
+def api_info(api_id: str) -> None:
+    """Get full API template info such as input details.
+
+    Example:
+      lightning aihub api_info API-ID
+
+    API-ID: The ID of the API for which information is requested.
+    """
+    ai_hub = AIHub()
+    ai_hub.api_info(api_id)
+
+
+@aihub.command(name="list-apis")
+@click.option("--search", default=None, help="Search for API templates by name.")
+def list_apis(search: Optional[str]) -> None:
+    """List API templates available in the AI Hub."""
+    ai_hub = AIHub()
+    ai_hub.list_apis(search=search)
+
+
+@aihub.command(name="deploy")
+@click.argument("api-id")
+@click.option(
+    "--cloud-account",
+    "--cloud_account",
+    default=None,
+    help="Cloud Account to deploy the API to. Defaults to user's default cloud account.",
+)
+@click.option("--name", default=None, help="Name of the deployed API. Defaults to the name of the API template.")
+@click.option(
+    "--teamspace",
+    default=None,
+    help="Teamspace to deploy the API to. Defaults to user's default teamspace.",
+)
+@click.option(
+    "--org",
+    default=None,
+    help="Organization to deploy the API to. Defaults to user's default organization.",
+)
+def deploy(
+    api_id: str, cloud_account: Optional[str], name: Optional[str], teamspace: Optional[str], org: Optional[str]
+) -> None:
+    """Deploy an API template from the AI Hub.
+
+    Example:
+      lightning aihub deploy API-ID
+
+    API-ID: The ID of the API which should be deployed.
+    """
+    ai_hub = AIHub()
+    ai_hub.run(api_id, cloud_account=cloud_account, name=name, teamspace=teamspace, org=org)

lightning_sdk/cli/legacy/clusters_menu.py

@@ -0,0 +1,49 @@
+import sys
+from typing import List, Optional
+
+from rich.console import Console
+from simple_term_menu import TerminalMenu
+
+from lightning_sdk import Teamspace
+from lightning_sdk.api.cloud_account_api import CloudAccountApi
+from lightning_sdk.lightning_cloud.openapi import V1ClusterType, V1ProjectClusterBinding
+
+
+class _ClustersMenu:
+    def _get_cluster_from_interactive_menu(self, possible_clusters: List[V1ProjectClusterBinding]) -> str:
+        terminal_menu = self._prepare_terminal_menu_teamspaces([cluster.cluster_id for cluster in possible_clusters])
+        terminal_menu.show()
+
+        return possible_clusters[terminal_menu.chosen_menu_index].cluster_id
+
+    @staticmethod
+    def _prepare_terminal_menu_teamspaces(cluster_ids: List[str]) -> TerminalMenu:
+        title = "Please select a cluster from the following:"
+
+        return TerminalMenu(cluster_ids, title=title, clear_menu_on_exit=True)
+
+    def _resolve_cluster(self, teamspace: Teamspace) -> Optional[str]:
+        selected_cluster_id = None
+        console = Console()
+        try:
+            selected_cluster_id = teamspace.default_cloud_account or self._get_cluster_from_interactive_menu(
+                possible_clusters=teamspace.cloud_account_objs
+            )
+
+            cloud_account_api = CloudAccountApi()
+
+            resolved_cluster_obj = cloud_account_api.get_cloud_account(
+                cloud_account_id=selected_cluster_id, org_id=teamspace.owner.id, teamspace_id=teamspace.id
+            )
+
+            return None if resolved_cluster_obj.spec.cluster_type == V1ClusterType.GLOBAL else resolved_cluster_obj.id
+        except KeyboardInterrupt:
+            console.print("Operation cancelled by user")
+            sys.exit(0)
+
+        except Exception:
+            console.print(
+                f"[red]Could not find the given Cluster:[/red] {selected_cluster_id}. "
+                "Please contact Lightning AI directly to resolve this issue."
+            )
+            sys.exit(1)