envloop-cli 1.16.0__py3-none-any.whl → 1.23.0__py3-none-any.whl

envloop/__init__.py

@@ -1,6 +1,13 @@
-"""EnvLoop Python client."""
-
+"""EnvLoop Python client, with optional functionality loaded on demand."""
+from ._optional import install_legacy_imports
 from .client import Client
-from .decision import DecisionClient
 
-__all__ = ["Client", "DecisionClient"]
+install_legacy_imports()
+__all__ = ['Client', 'DecisionClient']
+
+
+def __getattr__(name: str):
+    if name == 'DecisionClient':
+        from ._optional import feature_attribute
+        return feature_attribute('experiment', 'decision', name)
+    raise AttributeError(name)

envloop/_optional.py

@@ -0,0 +1,185 @@
+"""Lazy, static adapters for independently installed client features.
+
+No feature code is imported when the base client is imported or constructed.
+Legacy module names resolve to their single feature owner on explicit import.
+"""
+import argparse
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+from collections.abc import Sequence
+from importlib.machinery import ModuleSpec
+from types import ModuleType
+from typing import Any, override
+
+FEATURES = {'data': 'envloop_data', 'experiment': 'envloop_experiment', 'rsi-loop': 'envloop_rsi_loop'}
+FEATURE_COMMANDS = {
+    'data': {
+        'dataset': 'Discover datasets, revisions and tasks',
+        'data': 'Manage versioned Data resources and verified file downloads',
+        'runner': 'Discover available Runner revisions',
+        'checkpoint': 'List and download saved training checkpoints',
+        'profile': 'Manage platform runtime profiles',
+    },
+    'experiment': {
+        'job': 'Submit and manage Agent, Sandbox, Train and Inference Jobs',
+        'trail': 'Inspect and control existing trials',
+    },
+}
+
+MODULES: dict[str, str] = {
+    **dict.fromkeys('data data_publications data_upload data_cli profile_updates recipes'.split(), 'data'),
+    **dict.fromkeys('train train_progress train_runner_cli train_log_cli job_logs job_cost inference decision sandbox runtime_params job_spec_cli training'.split(), 'experiment'),
+    **dict.fromkeys('agent_runs rsi_cli'.split(), 'rsi-loop'),
+}
+CLIENTS = {
+    **{name: ('data', 'client') for name in ('ProfileService', 'RunnerService', 'Profiles', 'Runners')},
+    **{name: ('experiment', 'client') for name in ('TaskService', 'RpcService', 'load_task', 'validate_command', 'dataset_selector', 'Tasks', 'runner_selector', 'job_budget', 'Jobs')},
+    **{name: ('base', 'downloads') for name in ('ArtifactError', 'artifact_path')},
+}
+DATA_ENDPOINTS = set('open_download resolve_dataset list_runners profile_path put_profile list_profiles get_profile resolve_profile set_default_profile archive_profile revoke_profile_secret export_profile import_profile open_checkpoint_archive'.split())
+EXPERIMENT_ENDPOINTS = set('submit_job get_job get_job_result get_job_logs list_jobs job_action job_events stop_job list_trials get_task_run get_trial_detail get_trial_training list_trial_metrics list_trial_checkpoints get_task_result get_task_snapshot stop_task list_trial_artifacts open_trial_artifact'.split())
+
+
+class MissingFeatureError(ImportError):
+    """Static installation instructions, without reflecting user input."""
+    code = 'FEATURE_NOT_INSTALLED'
+
+    def __init__(self, feature: str):
+        self.feature = feature
+        super().__init__(f'Install optional functionality with: pip install "envloop-cli[{feature}]"')
+
+
+class CommandExit(Exception):
+    def __init__(self, status: int):
+        self.status = status
+
+
+def available(feature: str):
+    return importlib.util.find_spec(FEATURES[feature]) is not None
+
+
+def feature_module(feature: str, module: str):
+    if not available(feature):
+        raise MissingFeatureError(feature)
+    return importlib.import_module(f'{FEATURES[feature]}.{module}')
+
+
+def feature_attribute(feature: str, module: str, name: str):
+    if name.startswith('__'):
+        raise AttributeError(name)
+    return getattr(feature_module(feature, module), name)
+
+
+def client_attribute(name: str):
+    if name not in CLIENTS:
+        raise AttributeError(name)
+    feature, module = CLIENTS[name]
+    if feature == 'base':
+        return getattr(importlib.import_module(f'envloop.{module}'), name)
+    return feature_attribute(feature, module, name)
+
+
+def endpoint(name: str):
+    if name in DATA_ENDPOINTS:
+        feature = 'data'
+    elif name in EXPERIMENT_ENDPOINTS:
+        feature = 'experiment'
+    else:
+        raise AttributeError(name)
+    # Inspect the class dictionary: static methods retain their descriptor contract.
+    return feature_module(feature, 'http').Endpoints.__dict__[name]
+
+
+def navigation(name: str):
+    if name in {'Datasets', 'Checkpoints', '_checkpoint_matches', '_checkpoint_target', '_verified_checkpoint_file'}:
+        return feature_attribute('data', 'navigation_resources', name)
+    if name in {'Inference', 'InferenceResource'}:
+        return feature_attribute('experiment', 'navigation_resources', name)
+    raise AttributeError(name)
+
+
+def client_resource(client: Any, name: str):
+    server = client._transport
+    if name in {'billing', 'project', 'operations'}:
+        module, cls = ('resources', 'Operations') if name == 'operations' else ('navigation_resources', name.capitalize())
+        return getattr(importlib.import_module(f'envloop.{module}'), cls)(server)
+    if name == 'dashboard':
+        if available('experiment'):
+            return feature_attribute('experiment', 'navigation_resources', 'Dashboard')(client.project, client.jobs, client.train)
+        from .navigation_resources import Dashboard
+        return Dashboard(client.project)
+    if name in {'profiles', 'runners'}:
+        return feature_attribute('data', 'client', name.capitalize())(server)
+    if name in {'data', 'recipes'}:
+        return feature_attribute('data', name, name.capitalize())(server)
+    if name == 'datasets':
+        return navigation('Datasets')(server)
+    if name == 'checkpoints':
+        return feature_attribute('data', 'navigation_resources', 'Checkpoints')(server)
+    if name == 'jobs':
+        return feature_attribute('experiment', 'client', 'Jobs')(server)
+    if name == 'trials':
+        return client.tasks
+    if name == 'tasks':
+        return feature_attribute('experiment', 'client', 'Tasks')(server)
+    if name == 'training_jobs':
+        return client.train
+    if name == 'train':
+        return feature_attribute('experiment', 'train', 'TrainJobs')(server)
+    if name == 'decision':
+        return feature_attribute('experiment', 'decision', 'DecisionClient')(server)
+    if name == 'agent_runs':
+        return feature_attribute('rsi-loop', 'agent_runs', 'AgentRuns')(client.train)
+    if name in {'endpoints', 'adapters'}:
+        return feature_attribute('experiment', 'resources', name.capitalize())(server)
+    if name == 'inference':
+        return navigation('Inference')(server)
+    raise AttributeError(name)
+
+
+def execute_command(args: argparse.Namespace, client: Any, cli: Any):
+    if args.group in {'job', 'trail'}:
+        return getattr(feature_module('experiment', 'cli'), 'execute_' + args.group)(args, client, cli)
+    if args.group == 'profile':
+        return feature_module('data', 'cli').execute_profile(args, client, cli)
+    if args.group in {'data', 'dataset', 'runner', 'checkpoint'}:
+        return feature_module('data', 'resource_cli').execute(args, client)
+    from .resource_cli import execute
+    return execute(args, client)
+
+
+class _LegacyFeatureLoader(importlib.abc.Loader):
+    def __init__(self, feature: str, module: str):
+        self.feature, self.module = feature, module
+
+    @override
+    def create_module(self, spec: ModuleSpec):
+        module = feature_module(self.feature, self.module)
+        self.spec = module.__spec__
+        return module
+
+    @override
+    def exec_module(self, module: ModuleType):
+        # importlib rebinds __spec__ to the legacy alias; restore the feature module's own
+        # spec so its relative imports keep resolving inside the feature package.
+        module.__spec__ = self.spec
+
+
+class _LegacyFeatureFinder(importlib.abc.MetaPathFinder):
+    @override
+    def find_spec(self, fullname: str, path: Sequence[str] | None = None, target: ModuleType | None = None):
+        if not fullname.startswith('envloop.'):
+            return None
+        module = fullname.removeprefix('envloop.')
+        feature = MODULES.get(module)
+        if feature is None:
+            return None
+        loader = _LegacyFeatureLoader(feature, module)
+        return importlib.util.spec_from_loader(fullname, loader, is_package=module == 'training')
+
+
+def install_legacy_imports():
+    if not any(isinstance(finder, _LegacyFeatureFinder) for finder in sys.meta_path):
+        sys.meta_path.append(_LegacyFeatureFinder())

envloop/auth_cli.py

@@ -3,13 +3,14 @@ import argparse
 import json
 import os
 import sys
+from typing import Any, cast
 
 from .config import ConfigError, ConfigStore, normalize_url, validate_key
 
 DEFAULT_BASE_URL = "https://api.envloop.ai"
 
 
-def add_auth_commands(groups):
+def add_auth_commands(groups: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
     auth = groups.add_parser("auth", help="Configure credentials, inspect status, or remove a saved key")
     commands = auth.add_subparsers(dest="auth_command", required=True)
     login = commands.add_parser("login", help="Open the Clerk sign-in page and authorize CLI/SDK access")
@@ -47,7 +48,7 @@ def add_auth_commands(groups):
     workspace.add_argument("--stdin", action="store_true", help="Read the selected workspace's API key from stdin")
 
 
-def _key_from_input(stdin=False):
+def _key_from_input(stdin: bool = False) -> str:
     if stdin:
         value = sys.stdin.read(515)
         if value.endswith("\r\n"):
@@ -72,7 +73,7 @@ def _masked_key():
     masked[3] &= ~(termios.ECHO | termios.ICANON | termios.ISIG | termios.IEXTEN)
     masked[6][termios.VMIN] = 1
     masked[6][termios.VTIME] = 0
-    characters = []
+    characters: list[str] = []
     try:
         termios.tcsetattr(descriptor, termios.TCSAFLUSH, masked)
         sys.stderr.write("API key: ")
@@ -102,7 +103,7 @@ def _masked_key():
         sys.stderr.flush()
 
 
-def _report(args, store):
+def _report(args: argparse.Namespace, store: ConfigStore):
     saved, configured = store.inspect()
     from .cli import resolve_cli_connection
 
@@ -116,7 +117,7 @@ def _report(args, store):
     }, connection
 
 
-def _verify_key(url, key, workspace_id=None, project_id=None):
+def _verify_key(url: str, key: str, workspace_id: str | None = None, project_id: str | None = None):
     from .http import HttpService, RemoteError
 
     validate_key(key)
@@ -131,10 +132,10 @@ def _verify_key(url, key, workspace_id=None, project_id=None):
                                environment=False).request("GET", "/v1/me")
     except RemoteError as error:
         code = "EDGE_REJECTED" if error.code == "EDGE_REJECTED" else {
-            401: "AUTHENTICATION_REJECTED", 403: "AUTHORIZATION_DENIED"}.get(error.status_code)
+            401: "AUTHENTICATION_REJECTED", 403: "AUTHORIZATION_DENIED"}.get(cast(int, error.status_code))
         if code is None:
             code = error.code if error.status_code is None and error.code in {
-                "NETWORK_ERROR", "INVALID_RESPONSE", "RESPONSE_TOO_LARGE",
+                "NETWORK_ERROR", "REQUEST_TIMEOUT", "RESPONSE_INTERRUPTED", "INVALID_RESPONSE", "RESPONSE_TOO_LARGE",
             } else "HTTP_ERROR"
         raise ConfigError(code) from None
     if not isinstance(response, dict) or response.get("auth_method") != "api_key":
@@ -145,7 +146,7 @@ def _verify_key(url, key, workspace_id=None, project_id=None):
         return _scope(response, project=project_id)
 
 
-def _print(report, as_json=False):
+def _print(report: dict[str, Any], as_json: bool = False) -> None:
     if as_json:
         print(json.dumps(report, ensure_ascii=False))
         return
@@ -160,7 +161,7 @@ def _print(report, as_json=False):
     print(f"Check: {report['check']}")
 
 
-def run_auth(args, parser):
+def run_auth(args: argparse.Namespace, parser: argparse.ArgumentParser):
     store = ConfigStore()
     command = args.auth_command
     if command == "login":
@@ -198,20 +199,19 @@ def run_auth(args, parser):
                     raise ConfigError("API_URL_REQUIRED")
                 if not no_check:
                     scope = _verify_key(url, value, saved.get("workspace_id"), saved.get("project_id"))
+                if scope is not None:
+                    store.configure(url, value, expected_saved=saved, expected_credential=credential, scope=scope)
+                else:
+                    store.update(args.field, value, expected_url=url, expected_saved=saved, expected_credential=credential)
             elif args.field == "api-url":
                 if args.stdin:
                     parser.error("this field does not support --stdin")
                 value = args.value if args.value is not None else DEFAULT_BASE_URL
+                store.update(args.field, value)
             else:
                 if args.value is None or args.stdin:
                     parser.error("this field requires a value and does not support --stdin")
                 value = args.value
-            if args.field == "api-key":
-                if scope is not None:
-                    store.configure(url, value, expected_saved=saved, expected_credential=credential, scope=scope)
-                else:
-                    store.update(args.field, value, expected_url=url, expected_saved=saved, expected_credential=credential)
-            else:
                 store.update(args.field, value)
             if args.field == "api-key":
                 print("Saved. API key check: " + ("not_checked (offline)" if no_check else "authentication_confirmed"))
@@ -282,7 +282,7 @@ def run_auth(args, parser):
 
                 report["check"] = "edge_rejected" if getattr(error, "code", None) == "EDGE_REJECTED" else {
                     401: "authentication_rejected", 403: "authorization_denied"}.get(
-                    getattr(error, "status_code", None), safe_error_code(error))
+                    cast(int, getattr(error, "status_code", None)), safe_error_code(error))
                 _print(report, args.json)
                 print(format_error(error), file=sys.stderr)
                 return 1

envloop/auth_login.py

@@ -1,10 +1,12 @@
 """Browser authorization using a CLI-owned key and bounded anonymous polling."""
+import argparse
 import hashlib
 import json
 import secrets
 import time
 import webbrowser
 from http.client import InvalidURL
+from typing import Any, cast
 from urllib.error import HTTPError, URLError
 from urllib.parse import parse_qs, urlsplit
 from urllib.request import Request
@@ -14,7 +16,7 @@ from .config import ConfigError, normalize_url
 from .http import build_client_opener, error_fields
 
 
-def _request(url, action, body, timeout):
+def _request(url: str, action: str, body: dict[str, Any], timeout: float) -> dict[str, Any]:
     request = Request(url + '/v1/auth/cli/' + action, data=json.dumps(body).encode(),
                       headers={'Content-Type': 'application/json'}, method='POST')
     try:
@@ -34,11 +36,11 @@ def _request(url, action, body, timeout):
         raise ConfigError(code) from None
     except (URLError, TimeoutError, OSError, InvalidURL):
         raise ConfigError('NETWORK_ERROR') from None
-    except (ValueError, UnicodeError):
+    except ValueError:
         raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE') from None
 
 
-def _verification_url(url, response):
+def _verification_url(url: str, response: dict[str, Any]) -> tuple[str, str]:
     import re
 
     identifier = response.get('grant_id')
@@ -50,17 +52,19 @@ def _verification_url(url, response):
     try:
         page, api = urlsplit(uri), urlsplit(url)
         normalized = normalize_url(f'{page.scheme}://{page.netloc}')
-        expected = 'https://console.envloop.ai' if url == 'https://api.envloop.ai' else f'{api.scheme}://{api.netloc}'
+        # api.<domain> serves its sign-in page from console.<domain>; other addresses serve it themselves.
+        console = 'console.' + api.netloc.removeprefix('api.') if api.netloc.startswith('api.') else api.netloc
+        expected = f'{api.scheme}://{console}'
         if (f'{page.scheme}://{page.netloc}' != expected or page.path != '/sign-in' or page.fragment or
                 parse_qs(page.query, strict_parsing=True) != {'cli_login': [identifier]} or
                 normalized != expected):
             raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
-    except (ValueError, ConfigError):
+    except ValueError:
         raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE') from None
     return identifier, uri
 
 
-def login(args, store):
+def login(args: argparse.Namespace, store: Any) -> int:
     from .auth_cli import DEFAULT_BASE_URL
     from .cli import resolve_cli_connection
 
@@ -69,7 +73,7 @@ def login(args, store):
     deadline = time.monotonic() + args.timeout
     key, poll_token = 'epk_' + secrets.token_hex(32), secrets.token_urlsafe(32)
     code = ''.join(secrets.choice('ABCDEFGHJKLMNPQRSTUVWXYZ23456789') for _ in range(8))
-    def digest(value):
+    def digest(value: str) -> str:
         return hashlib.sha256(value.encode()).hexdigest()
     response = _request(url, 'start', {'key_hash': digest(key), 'poll_hash': digest(poll_token),
                                     'code_hash': digest(code)}, min(5, args.timeout))
@@ -106,7 +110,7 @@ def login(args, store):
                 continue
             if result.get('status') == 'approved':
                 # Verify the exact scope before committing the saved connection.
-                scope = _identity(url, key, result.get('workspace_id'), result.get('project_id'), details=True)
+                scope = cast(dict[str, Any], _identity(url, key, result.get('workspace_id'), result.get('project_id'), details=True))
                 if (not result.get('workspace_id') or not result.get('project_id') or
                         scope.get('project_id') != result['project_id']):
                     raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')

envloop/auth_workspace.py

@@ -1,13 +1,15 @@
 """Verified workspace selection with scoped credentials and a terminal picker."""
+import argparse
 import os
 import select
 import sys
+from typing import Any, cast
 
-from .config import ConfigError, validate_project, validate_workspace
+from .config import ConfigError, ConfigStore, validate_project, validate_workspace
 from .http import HttpService, RemoteError
 
 
-def _request(url, key, path, workspace=None, project=None):
+def _request(url: str, key: str, path: str, workspace: str | None = None, project: str | None = None):
     try:
         return HttpService(url, api_key=key, workspace_id=workspace, project_id=project, timeout=5,
                            config=False, environment=False).request('GET', path)
@@ -17,17 +19,17 @@ def _request(url, key, path, workspace=None, project=None):
         if path.startswith('/v1/workspaces/') and path.endswith('/projects') and error.status_code == 403 and error.code == 'ACCESS_DENIED':
             raise ConfigError('PROJECT_LIST_REQUIRES_SESSION') from None
         fallback = error.code if error.status_code is None and error.code in {
-            'NETWORK_ERROR', 'INVALID_RESPONSE', 'RESPONSE_TOO_LARGE',
+            'NETWORK_ERROR', 'REQUEST_TIMEOUT', 'RESPONSE_INTERRUPTED', 'INVALID_RESPONSE', 'RESPONSE_TOO_LARGE',
         } else 'HTTP_ERROR'
         denied = 'PROJECT_ACCESS_DENIED' if project is not None else 'WORKSPACE_ACCESS_DENIED'
-        code = {401: 'AUTHENTICATION_REJECTED', 403: denied, 404: denied}.get(error.status_code, fallback)
+        code = {401: 'AUTHENTICATION_REJECTED', 403: denied, 404: denied}.get(cast(int, error.status_code), fallback)
         raise ConfigError(code) from None
 
 
-def _scope(response, workspace=None, project=None):
+def _scope(response: Any, workspace: str | None = None, project: str | None = None):
     if not isinstance(response, dict) or response.get('auth_method') != 'api_key':
         raise ConfigError('AUTH_CHECK_UNCONFIRMED')
-    scope = response.get('workspace')
+    scope: Any = response.get('workspace')
     try:
         identifier = validate_workspace(scope['workspace_id'])
     except (KeyError, TypeError, ConfigError):
@@ -50,12 +52,12 @@ def _scope(response, workspace=None, project=None):
     return result
 
 
-def _identity(url, key, workspace=None, project=None, *, details=False):
+def _identity(url: str, key: str, workspace: str | None = None, project: str | None = None, *, details: bool = False) -> Any:
     result = _scope(_request(url, key, '/v1/me', workspace, project), workspace, project)
     return result if details else result['workspace_id']
 
 
-def _workspaces(url, key, fallback):
+def _workspaces(url: str, key: str, fallback: list[dict[str, Any]]):
     local_only = False
     try:
         response = _request(url, key, '/v1/workspaces')
@@ -70,7 +72,7 @@ def _workspaces(url, key, fallback):
         raise ConfigError('WORKSPACE_PAGINATION_UNSUPPORTED')
     if not isinstance(items, list) or len(items) > 1000:
         raise ConfigError('INVALID_WORKSPACE_RESPONSE')
-    result, seen = [], set()
+    result, seen = cast(list[tuple[str, str]], []), set()
     for item in items:
         try:
             workspace = validate_workspace(item['workspace_id'])
@@ -88,7 +90,7 @@ def _workspaces(url, key, fallback):
     return result, local_only
 
 
-def _projects(url, key, current, saved_projects):
+def _projects(url: str, key: str, current: dict[str, Any], saved_projects: dict[str, Any]):
     workspace = current['workspace_id']
     local_only = False
     try:
@@ -107,7 +109,7 @@ def _projects(url, key, current, saved_projects):
         raise ConfigError('PROJECT_PAGINATION_UNSUPPORTED')
     if not isinstance(items, list) or len(items) > 1000:
         raise ConfigError('INVALID_PROJECT_RESPONSE')
-    result, seen = [], set()
+    result, seen = cast(list[tuple[str, str]], []), set()
     for item in items:
         try:
             project = validate_project(item['project_id'])
@@ -124,7 +126,7 @@ def _projects(url, key, current, saved_projects):
     return result, local_only
 
 
-def select_project(url, current_key, current, saved_projects, *, target=None, stdin=False):
+def select_project(url: str, current_key: str, current: dict[str, Any], saved_projects: dict[str, Any], *, target: str | None = None, stdin: bool = False):
     """Choose and verify a scoped key without writing configuration."""
     from .auth_cli import _key_from_input
 
@@ -152,7 +154,7 @@ def select_project(url, current_key, current, saved_projects, *, target=None, st
     return key, selected
 
 
-def configure_project(args, store):
+def configure_project(args: argparse.Namespace, store: ConfigStore):
     from .auth_cli import _print, _report
 
     target = args.project_id
@@ -184,7 +186,7 @@ def configure_project(args, store):
     return 0
 
 
-def _choose(items, current, label='workspace'):
+def _choose(items: list[tuple[str, str]], current: str | None, label: str = 'workspace'):
     import termios
     import tty
 
@@ -224,7 +226,7 @@ def _choose(items, current, label='workspace'):
         termios.tcsetattr(descriptor, termios.TCSAFLUSH, original)
 
 
-def configure_workspace(args, store):
+def configure_workspace(args: argparse.Namespace, store: ConfigStore):
     from .auth_cli import _key_from_input, _print, _report
 
     target = args.workspace_id