superkernel-adapter 0.9.7__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- superkernel_adapter/__init__.py +25 -0
- superkernel_adapter/kernel.py +646 -0
- superkernel_adapter/launcher.py +40 -0
- superkernel_adapter/logfile.py +28 -0
- superkernel_adapter/schema.py +179 -0
- superkernel_adapter/state.py +217 -0
- superkernel_adapter-0.9.7.dist-info/METADATA +132 -0
- superkernel_adapter-0.9.7.dist-info/RECORD +12 -0
- superkernel_adapter-0.9.7.dist-info/WHEEL +5 -0
- superkernel_adapter-0.9.7.dist-info/entry_points.txt +2 -0
- superkernel_adapter-0.9.7.dist-info/licenses/LICENSE +201 -0
- superkernel_adapter-0.9.7.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Environment-local launcher discovery without loading the ipykernel."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import sysconfig
|
|
7
|
+
from collections.abc import Sequence
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def adapter_executable() -> Path:
|
|
12
|
+
"""Return this Python environment's installed, executable console script."""
|
|
13
|
+
scripts = sysconfig.get_path("scripts")
|
|
14
|
+
if not scripts:
|
|
15
|
+
raise RuntimeError("Python scripts directory is unavailable")
|
|
16
|
+
launcher = Path(scripts) / ("superkernel.exe" if os.name == "nt" else "superkernel")
|
|
17
|
+
if not launcher.is_file() or not os.access(launcher, os.X_OK):
|
|
18
|
+
raise RuntimeError(
|
|
19
|
+
"Install superkernel-adapter in the selected Python environment"
|
|
20
|
+
)
|
|
21
|
+
return launcher.absolute()
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def is_adapter_invocation(
|
|
25
|
+
arguments: Sequence[str], *, allow_previous: bool = False
|
|
26
|
+
) -> bool:
|
|
27
|
+
"""Recognize console processes; previous identities are cleanup-only."""
|
|
28
|
+
for executable in arguments[:2]:
|
|
29
|
+
if Path(executable).is_absolute() and Path(executable).name in {
|
|
30
|
+
"superkernel",
|
|
31
|
+
"superkernel.exe",
|
|
32
|
+
}:
|
|
33
|
+
return True
|
|
34
|
+
if allow_previous:
|
|
35
|
+
# Explicit shutdown of pre-migration adapters only, never a launch alias.
|
|
36
|
+
return any(
|
|
37
|
+
arguments[index] == "-m" and arguments[index + 1] == "superkernels.kernel"
|
|
38
|
+
for index in range(len(arguments) - 1)
|
|
39
|
+
)
|
|
40
|
+
return False
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Best-effort logging for the local SuperKernels runtime."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import datetime as dt
|
|
6
|
+
import sys
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
DEFAULT_LOG_FILE = Path("/var/superkernel.log")
|
|
10
|
+
|
|
11
|
+
PathLike = str | Path
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def append_log(message: str, log_path: PathLike | None = DEFAULT_LOG_FILE) -> None:
|
|
15
|
+
"""
|
|
16
|
+
Append a timestamped message to the log file.
|
|
17
|
+
Silently ignores filesystem errors so logging never breaks core flows.
|
|
18
|
+
"""
|
|
19
|
+
if log_path is None:
|
|
20
|
+
log_path = DEFAULT_LOG_FILE
|
|
21
|
+
path = Path(log_path).expanduser()
|
|
22
|
+
try:
|
|
23
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
24
|
+
stamp = dt.datetime.now(dt.timezone.utc).isoformat(timespec="milliseconds")
|
|
25
|
+
with path.open("a", encoding="utf-8") as fh:
|
|
26
|
+
fh.write(f"[{stamp}] {message}\n")
|
|
27
|
+
except OSError as exc:
|
|
28
|
+
sys.stderr.write(f"[Super Kernel] Failed to write log entry: {exc}\n")
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
"""Shared models for the Super Kernel Gateway contract."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import datetime as dt
|
|
6
|
+
from typing import Any, Literal
|
|
7
|
+
|
|
8
|
+
from pydantic import BaseModel, ConfigDict, Field
|
|
9
|
+
|
|
10
|
+
KernelType = Literal["base", "mpi", "torch"]
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class AuthRequest(BaseModel):
|
|
14
|
+
"""API-key login request sent only to ``POST /auth``."""
|
|
15
|
+
|
|
16
|
+
model_config = ConfigDict(extra="forbid")
|
|
17
|
+
|
|
18
|
+
method: Literal["api_key"] = "api_key"
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class AuthResponse(BaseModel):
|
|
22
|
+
"""Reusable Gateway session shared by infrastructure and kernel calls."""
|
|
23
|
+
|
|
24
|
+
model_config = ConfigDict(extra="forbid")
|
|
25
|
+
|
|
26
|
+
access_token: str = Field(min_length=1)
|
|
27
|
+
token_type: Literal["Bearer"] = "Bearer"
|
|
28
|
+
auth_method: Literal["api_key"] = "api_key"
|
|
29
|
+
user_id: str = Field(min_length=1, max_length=320)
|
|
30
|
+
expires_at: dt.datetime
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class RuntimeDescriptor(BaseModel):
|
|
34
|
+
"""One runtime image available through ``POST /infra/status``."""
|
|
35
|
+
|
|
36
|
+
model_config = ConfigDict(extra="forbid")
|
|
37
|
+
|
|
38
|
+
type: KernelType
|
|
39
|
+
name: str = Field(min_length=1, max_length=64)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class ResourceAmount(BaseModel):
|
|
43
|
+
"""One resource limit and its current reservation."""
|
|
44
|
+
|
|
45
|
+
model_config = ConfigDict(extra="forbid")
|
|
46
|
+
|
|
47
|
+
limit: int = Field(ge=0)
|
|
48
|
+
used: int = Field(ge=0)
|
|
49
|
+
available: int = Field(ge=0)
|
|
50
|
+
unit: Literal["count", "bytes"]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class UserResourceResponse(BaseModel):
|
|
54
|
+
"""Authenticated user's resource limits and reservations."""
|
|
55
|
+
|
|
56
|
+
model_config = ConfigDict(extra="forbid")
|
|
57
|
+
|
|
58
|
+
vcpu: ResourceAmount
|
|
59
|
+
memory: ResourceAmount | None = None
|
|
60
|
+
gpu: ResourceAmount
|
|
61
|
+
block: ResourceAmount
|
|
62
|
+
bucket: ResourceAmount
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class InfraKernelCreateRequest(BaseModel):
|
|
66
|
+
"""Idempotent kernel specification for ``POST /infra/kernel/create``."""
|
|
67
|
+
|
|
68
|
+
model_config = ConfigDict(extra="forbid", populate_by_name=True)
|
|
69
|
+
|
|
70
|
+
request_id: str = Field(min_length=1, max_length=128)
|
|
71
|
+
name: str = Field(min_length=1, max_length=128)
|
|
72
|
+
kernel_type: KernelType = Field(alias="type")
|
|
73
|
+
runtime: str = Field(min_length=1, max_length=64)
|
|
74
|
+
nodes: int = Field(default=1, ge=1, le=32)
|
|
75
|
+
vcpu_per_node: int = Field(default=1, ge=1, le=64)
|
|
76
|
+
memory_per_vcpu_gb: int = Field(default=1, ge=1, le=128)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class InfraKernelActionRequest(BaseModel):
|
|
80
|
+
"""Kernel identity for one infrastructure lifecycle mutation."""
|
|
81
|
+
|
|
82
|
+
model_config = ConfigDict(extra="forbid")
|
|
83
|
+
|
|
84
|
+
kernel_id: str = Field(min_length=1, max_length=128)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class InfraKernelResponse(BaseModel):
|
|
88
|
+
"""Infrastructure create/start/stop/delete result."""
|
|
89
|
+
|
|
90
|
+
model_config = ConfigDict(extra="forbid")
|
|
91
|
+
|
|
92
|
+
kernel_id: str = Field(min_length=1)
|
|
93
|
+
status: Literal["ready", "paused", "deleted"]
|
|
94
|
+
metadata: dict[str, Any] = Field(default_factory=dict)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class InfraKernelStatus(BaseModel):
|
|
98
|
+
"""One owned kernel returned in the infrastructure status snapshot."""
|
|
99
|
+
|
|
100
|
+
model_config = ConfigDict(extra="forbid")
|
|
101
|
+
|
|
102
|
+
kernel_id: str = Field(min_length=1)
|
|
103
|
+
request_id: str = Field(min_length=1)
|
|
104
|
+
name: str = Field(min_length=1)
|
|
105
|
+
type: KernelType
|
|
106
|
+
runtime: str = Field(min_length=1)
|
|
107
|
+
nodes: int = Field(ge=1)
|
|
108
|
+
vcpu_per_node: int = Field(ge=1)
|
|
109
|
+
memory_per_vcpu_gb: int = Field(ge=1)
|
|
110
|
+
status: Literal["idle", "busy", "degraded", "unavailable", "paused"]
|
|
111
|
+
generation: int = Field(ge=1)
|
|
112
|
+
healthy_runners: int = Field(ge=0)
|
|
113
|
+
busy_runners: int = Field(ge=0)
|
|
114
|
+
idle_runners: int = Field(ge=0)
|
|
115
|
+
expected_runners: int = Field(ge=1)
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class InfraStatusResponse(BaseModel):
|
|
119
|
+
"""Complete plugin-facing Gateway snapshot."""
|
|
120
|
+
|
|
121
|
+
model_config = ConfigDict(extra="forbid")
|
|
122
|
+
|
|
123
|
+
user_id: str = Field(min_length=1, max_length=320)
|
|
124
|
+
resources: UserResourceResponse
|
|
125
|
+
runtimes: list[RuntimeDescriptor]
|
|
126
|
+
kernels: list[InfraKernelStatus]
|
|
127
|
+
updated_at: dt.datetime
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
class CodeExecutionRequest(BaseModel):
|
|
131
|
+
"""Initial cell admission sent to ``POST /kernel/execute``."""
|
|
132
|
+
|
|
133
|
+
model_config = ConfigDict(extra="forbid")
|
|
134
|
+
|
|
135
|
+
mode: Literal["execute"] = "execute"
|
|
136
|
+
kernel_id: str = Field(min_length=1, max_length=128)
|
|
137
|
+
execution_id: str = Field(min_length=1, max_length=128)
|
|
138
|
+
code: str = Field(min_length=1, max_length=1_000_000)
|
|
139
|
+
execution_count: int | None = None
|
|
140
|
+
session_id: str = Field(min_length=1, max_length=128)
|
|
141
|
+
metadata: dict[str, Any] = Field(default_factory=dict)
|
|
142
|
+
|
|
143
|
+
def require_code(self) -> str:
|
|
144
|
+
"""Return non-empty code for the execution handler."""
|
|
145
|
+
if not self.code.strip():
|
|
146
|
+
raise ValueError("code cannot be empty")
|
|
147
|
+
return self.code
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
class CodeExecutionResumeRequest(BaseModel):
|
|
151
|
+
"""SSE replay attachment for one already-admitted execution."""
|
|
152
|
+
|
|
153
|
+
model_config = ConfigDict(extra="forbid")
|
|
154
|
+
|
|
155
|
+
mode: Literal["resume"] = "resume"
|
|
156
|
+
kernel_id: str = Field(min_length=1, max_length=128)
|
|
157
|
+
reply_id: str = Field(pattern=r"^skr_[A-Za-z0-9_-]{16,128}$")
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class ControlRequest(BaseModel):
|
|
161
|
+
"""Body sent by ``superkernel_adapter.kernel`` to ``POST /kernel/control``."""
|
|
162
|
+
|
|
163
|
+
model_config = ConfigDict(extra="forbid")
|
|
164
|
+
|
|
165
|
+
action: Literal["interrupt", "restart"]
|
|
166
|
+
kernel_id: str = Field(min_length=1, max_length=128)
|
|
167
|
+
session_id: str | None = Field(default=None, min_length=1, max_length=128)
|
|
168
|
+
execution_id: str | None = Field(default=None, min_length=1, max_length=128)
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
class ControlResponse(BaseModel):
|
|
172
|
+
"""Synchronous kernel-control result."""
|
|
173
|
+
|
|
174
|
+
model_config = ConfigDict(extra="forbid")
|
|
175
|
+
|
|
176
|
+
kernel_id: str
|
|
177
|
+
action: Literal["interrupt", "restart"]
|
|
178
|
+
status: Literal["interrupted", "idle", "restarted"]
|
|
179
|
+
execution_id: str | None = None
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
"""Private local state access required by the SuperKernels runtime."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import datetime as dt
|
|
6
|
+
import hashlib
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import re
|
|
10
|
+
import stat
|
|
11
|
+
import time
|
|
12
|
+
from collections.abc import Iterator
|
|
13
|
+
from contextlib import contextmanager
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from urllib.parse import urlsplit, urlunsplit
|
|
16
|
+
|
|
17
|
+
REMOTE_KERNEL_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
|
|
18
|
+
LOCAL_SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def _shared_state_dir() -> Path:
|
|
22
|
+
configured = os.getenv("SUPERKERNEL_HOME", "").strip()
|
|
23
|
+
return Path(configured).expanduser() if configured else Path.home() / ".superkernel"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _normalize_gateway_url(value: str) -> str:
|
|
27
|
+
parsed = urlsplit(value.strip())
|
|
28
|
+
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
|
|
29
|
+
raise RuntimeError("Invalid Super Kernel Gateway URL")
|
|
30
|
+
if parsed.username or parsed.password or parsed.query or parsed.fragment:
|
|
31
|
+
raise RuntimeError("Invalid Super Kernel Gateway URL")
|
|
32
|
+
path = parsed.path.rstrip("/")
|
|
33
|
+
return urlunsplit((parsed.scheme.lower(), parsed.netloc.lower(), path, "", ""))
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _gateway_id(gateway_url: str) -> str:
|
|
37
|
+
normalized = _normalize_gateway_url(gateway_url)
|
|
38
|
+
return f"gw_{hashlib.sha256(normalized.encode()).hexdigest()[:16]}"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _validate_remote_kernel_id(remote_kernel_id: str) -> str:
|
|
42
|
+
if not REMOTE_KERNEL_ID_PATTERN.fullmatch(remote_kernel_id):
|
|
43
|
+
raise RuntimeError("Invalid remote Super Kernel ID")
|
|
44
|
+
return remote_kernel_id
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _ensure_private_directory(path: Path) -> Path:
|
|
48
|
+
try:
|
|
49
|
+
details = path.lstat()
|
|
50
|
+
except FileNotFoundError:
|
|
51
|
+
path.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
52
|
+
details = path.lstat()
|
|
53
|
+
if (
|
|
54
|
+
not stat.S_ISDIR(details.st_mode)
|
|
55
|
+
or stat.S_ISLNK(details.st_mode)
|
|
56
|
+
or details.st_uid != os.geteuid()
|
|
57
|
+
):
|
|
58
|
+
raise RuntimeError("Unsafe Super Kernel state directory")
|
|
59
|
+
path.chmod(0o700)
|
|
60
|
+
return path
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@contextmanager
|
|
64
|
+
def _shared_state_lock() -> Iterator[None]:
|
|
65
|
+
"""Use the same directory lock as both management clients."""
|
|
66
|
+
lock_dir = _ensure_private_directory(_shared_state_dir()) / ".write-lock"
|
|
67
|
+
for _ in range(80):
|
|
68
|
+
try:
|
|
69
|
+
lock_dir.mkdir(mode=0o700)
|
|
70
|
+
break
|
|
71
|
+
except FileExistsError:
|
|
72
|
+
try:
|
|
73
|
+
details = lock_dir.lstat()
|
|
74
|
+
if (
|
|
75
|
+
stat.S_ISDIR(details.st_mode)
|
|
76
|
+
and details.st_uid == os.geteuid()
|
|
77
|
+
and time.time() - details.st_mtime > 30
|
|
78
|
+
):
|
|
79
|
+
lock_dir.rmdir()
|
|
80
|
+
continue
|
|
81
|
+
except OSError:
|
|
82
|
+
continue
|
|
83
|
+
time.sleep(0.025)
|
|
84
|
+
else:
|
|
85
|
+
raise RuntimeError("Super Kernel state is busy")
|
|
86
|
+
try:
|
|
87
|
+
yield
|
|
88
|
+
finally:
|
|
89
|
+
lock_dir.rmdir()
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _read_auth_token(auth_file: str, gateway_url: str | None = None) -> str:
|
|
93
|
+
"""Read the current UI-provisioned Gateway session without caching it."""
|
|
94
|
+
path = Path(auth_file).expanduser()
|
|
95
|
+
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
|
|
96
|
+
try:
|
|
97
|
+
descriptor = os.open(path, flags)
|
|
98
|
+
except OSError as exc:
|
|
99
|
+
raise RuntimeError("Super Kernel authentication is unavailable") from exc
|
|
100
|
+
try:
|
|
101
|
+
details = os.fstat(descriptor)
|
|
102
|
+
if not stat.S_ISREG(details.st_mode):
|
|
103
|
+
raise RuntimeError("Invalid Super Kernel auth file")
|
|
104
|
+
if details.st_uid != os.geteuid() or stat.S_IMODE(details.st_mode) & 0o077:
|
|
105
|
+
raise RuntimeError("Unsafe Super Kernel auth file permissions")
|
|
106
|
+
with os.fdopen(descriptor, encoding="utf-8") as stream:
|
|
107
|
+
descriptor = -1
|
|
108
|
+
payload = json.load(stream)
|
|
109
|
+
except (OSError, ValueError, json.JSONDecodeError) as exc:
|
|
110
|
+
raise RuntimeError("Cannot read Super Kernel authentication") from exc
|
|
111
|
+
finally:
|
|
112
|
+
if descriptor >= 0:
|
|
113
|
+
os.close(descriptor)
|
|
114
|
+
token = payload.get("access_token") if isinstance(payload, dict) else None
|
|
115
|
+
if not isinstance(token, str) or not token.startswith("sks_"):
|
|
116
|
+
raise RuntimeError("Super Kernel authentication is unavailable")
|
|
117
|
+
try:
|
|
118
|
+
expires = dt.datetime.fromisoformat(
|
|
119
|
+
payload["expires_at"].replace("Z", "+00:00")
|
|
120
|
+
)
|
|
121
|
+
valid = (
|
|
122
|
+
payload.get("version") == 1
|
|
123
|
+
and payload.get("auth_method") == "api_key"
|
|
124
|
+
and payload.get("token_type") == "Bearer"
|
|
125
|
+
and isinstance(payload.get("user_id"), str)
|
|
126
|
+
and bool(payload["user_id"].strip())
|
|
127
|
+
and expires.tzinfo is not None
|
|
128
|
+
and expires > dt.datetime.now(dt.timezone.utc)
|
|
129
|
+
)
|
|
130
|
+
saved_gateway = _normalize_gateway_url(payload["gateway_url"])
|
|
131
|
+
if gateway_url is not None:
|
|
132
|
+
valid = valid and saved_gateway == _normalize_gateway_url(gateway_url)
|
|
133
|
+
except (KeyError, TypeError, ValueError, AttributeError) as exc:
|
|
134
|
+
raise RuntimeError("Invalid Super Kernel authentication") from exc
|
|
135
|
+
if not valid:
|
|
136
|
+
raise RuntimeError("Super Kernel authentication is invalid or expired")
|
|
137
|
+
return token
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _runtime_status_file(
|
|
141
|
+
gateway_url: str,
|
|
142
|
+
remote_kernel_id: str,
|
|
143
|
+
session_id: str,
|
|
144
|
+
) -> Path:
|
|
145
|
+
if not LOCAL_SESSION_ID_PATTERN.fullmatch(session_id):
|
|
146
|
+
raise RuntimeError("Invalid local Super Kernel session ID")
|
|
147
|
+
return (
|
|
148
|
+
_shared_state_dir()
|
|
149
|
+
/ _gateway_id(gateway_url)
|
|
150
|
+
/ "runtime"
|
|
151
|
+
/ _validate_remote_kernel_id(remote_kernel_id)
|
|
152
|
+
/ f"{session_id}.json"
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def _write_runtime_status(
|
|
157
|
+
gateway_url: str,
|
|
158
|
+
remote_kernel_id: str,
|
|
159
|
+
session_id: str,
|
|
160
|
+
status: str,
|
|
161
|
+
last_execution_at: float | None = None,
|
|
162
|
+
) -> None:
|
|
163
|
+
"""Publish a non-secret runtime observation for both plugin UIs."""
|
|
164
|
+
with _shared_state_lock():
|
|
165
|
+
_write_runtime_status_locked(
|
|
166
|
+
gateway_url, remote_kernel_id, session_id, status, last_execution_at
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _write_runtime_status_locked(
|
|
171
|
+
gateway_url: str,
|
|
172
|
+
remote_kernel_id: str,
|
|
173
|
+
session_id: str,
|
|
174
|
+
status: str,
|
|
175
|
+
last_execution_at: float | None,
|
|
176
|
+
) -> None:
|
|
177
|
+
if status not in {"idle", "busy", "error"}:
|
|
178
|
+
raise RuntimeError("Invalid local Super Kernel status")
|
|
179
|
+
root = _ensure_private_directory(_shared_state_dir())
|
|
180
|
+
gateway_dir = _ensure_private_directory(root / _gateway_id(gateway_url))
|
|
181
|
+
runtime_dir = _ensure_private_directory(gateway_dir / "runtime")
|
|
182
|
+
kernel_dir = _ensure_private_directory(
|
|
183
|
+
runtime_dir / _validate_remote_kernel_id(remote_kernel_id)
|
|
184
|
+
)
|
|
185
|
+
status_file = _runtime_status_file(gateway_url, remote_kernel_id, session_id)
|
|
186
|
+
temporary = kernel_dir / (f".{status_file.name}.{os.getpid()}.{time.time_ns()}.tmp")
|
|
187
|
+
descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
|
|
188
|
+
try:
|
|
189
|
+
with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
|
|
190
|
+
stream.write(
|
|
191
|
+
json.dumps(
|
|
192
|
+
{
|
|
193
|
+
"version": 1,
|
|
194
|
+
"gateway_url": _normalize_gateway_url(gateway_url),
|
|
195
|
+
"remote_kernel_id": remote_kernel_id,
|
|
196
|
+
"session_id": session_id,
|
|
197
|
+
"status": status,
|
|
198
|
+
"updated_at": time.time(),
|
|
199
|
+
"last_execution_at": last_execution_at,
|
|
200
|
+
"pid": os.getpid(),
|
|
201
|
+
}
|
|
202
|
+
),
|
|
203
|
+
)
|
|
204
|
+
os.replace(temporary, status_file)
|
|
205
|
+
finally:
|
|
206
|
+
temporary.unlink(missing_ok=True)
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _delete_runtime_status(
|
|
210
|
+
gateway_url: str,
|
|
211
|
+
remote_kernel_id: str,
|
|
212
|
+
session_id: str,
|
|
213
|
+
) -> None:
|
|
214
|
+
with _shared_state_lock():
|
|
215
|
+
_runtime_status_file(gateway_url, remote_kernel_id, session_id).unlink(
|
|
216
|
+
missing_ok=True
|
|
217
|
+
)
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: superkernel-adapter
|
|
3
|
+
Version: 0.9.7
|
|
4
|
+
Summary: SuperKernel Adapter: a shared local Jupyter kernel for remote compute.
|
|
5
|
+
Author-email: Leo Li <leoustc@icloud.com>
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://superkernel.leoustc.com
|
|
8
|
+
Project-URL: Source, https://github.com/leoustc/superkernel/tree/main/superkernel-adapter
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Framework :: Jupyter
|
|
14
|
+
Requires-Python: >=3.10
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Requires-Dist: ipykernel>=6.29
|
|
18
|
+
Requires-Dist: pydantic>=2.7
|
|
19
|
+
Requires-Dist: requests>=2.31
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# SuperKernel Adapter
|
|
23
|
+
|
|
24
|
+
SuperKernel Adapter connects ordinary Jupyter notebooks to remote Super Kernel compute.
|
|
25
|
+
|
|
26
|
+
It is a Jupyter-compatible Python kernel that connects a local notebook to a
|
|
27
|
+
configured SuperKernel runtime. Your existing Jupyter tools continue to manage
|
|
28
|
+
the notebook connection while code runs on the selected remote Python, MPI, or
|
|
29
|
+
PyTorch environment.
|
|
30
|
+
|
|
31
|
+
## Features
|
|
32
|
+
|
|
33
|
+
- Works as a standard Jupyter kernel in JupyterLab and VS Code.
|
|
34
|
+
- Streams remote output back to notebook cells as it is produced.
|
|
35
|
+
- Preserves a separate Python namespace for each notebook session.
|
|
36
|
+
- Executes cells sequentially and supports interrupt and restart actions.
|
|
37
|
+
- Reconnects interrupted output streams without submitting the cell twice.
|
|
38
|
+
- Keeps authentication tokens out of Jupyter kernelspecs and command-line
|
|
39
|
+
arguments.
|
|
40
|
+
|
|
41
|
+
This is the shared host adapter for both the VS Code and Jupyter plugins.
|
|
42
|
+
Local runtime records describe notebook sessions, not remote runner health.
|
|
43
|
+
Publication and shutdown cleanup use the shared client-state lock, and each
|
|
44
|
+
record retains its last cell-start timestamp across heartbeat refreshes.
|
|
45
|
+
|
|
46
|
+
Silent requests still execute but suppress notebook output. If a connection
|
|
47
|
+
failure leaves an execution unresolved, rerun its original code to resume it;
|
|
48
|
+
different code is rejected until the previous result is recovered or the kernel
|
|
49
|
+
is restarted. Code is never automatically replayed after a lost reply handle.
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
SuperKernel Adapter requires Python 3.10 or newer.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
uv pip install superkernel-adapter
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Until this renamed distribution is published, install a provided wheel instead:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
uv pip install superkernel_adapter-0.9.7-py3-none-any.whl
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The JupyterLab or VS Code SuperKernel integration normally installs and
|
|
66
|
+
configures the notebook kernels for you. A configured kernel can then be
|
|
67
|
+
selected from the standard Jupyter kernel picker like any other kernel.
|
|
68
|
+
|
|
69
|
+
This package contains the notebook runtime only. Gateway login, remote runtime
|
|
70
|
+
creation, and local kernel registration are handled by a compatible
|
|
71
|
+
SuperKernel client integration.
|
|
72
|
+
|
|
73
|
+
The distribution is `superkernel-adapter`, the Python import is
|
|
74
|
+
`superkernel_adapter`, the console launcher is `superkernel`, and the kernel
|
|
75
|
+
class remains `SuperKernel`.
|
|
76
|
+
|
|
77
|
+
## Python API
|
|
78
|
+
|
|
79
|
+
The kernel class is available for integrations that need to inspect or extend
|
|
80
|
+
the local runtime:
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from superkernel_adapter import SuperKernel
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The supported process entry point for a configured Jupyter kernelspec is:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
superkernel
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Its connection and authentication arguments are generated by the client
|
|
93
|
+
integration and are not intended to be entered manually.
|
|
94
|
+
Clients use the selected Python environment's absolute scripts path, such as
|
|
95
|
+
`/opt/jupyterhub/bin/superkernel` (or `Scripts/superkernel.exe` on Windows),
|
|
96
|
+
not a PATH lookup or `python -m` wrapper. Installing this package creates that
|
|
97
|
+
launcher automatically with the environment's Python interpreter.
|
|
98
|
+
|
|
99
|
+
## Upgrading from superkernels
|
|
100
|
+
|
|
101
|
+
Upgrade both management plugins together with this adapter. They regenerate
|
|
102
|
+
canonical kernelspec launch commands while retaining the existing
|
|
103
|
+
`~/.superkernel` version-1 records, sessions, kernel IDs and workspace files.
|
|
104
|
+
Restart notebook kernels and reload the VS Code window after installation.
|
|
105
|
+
The retired distribution/import has no runtime alias; the root local install
|
|
106
|
+
workflow removes it after installing the new adapter. An already-running old
|
|
107
|
+
process may be recognized only for explicit, identity-checked shutdown.
|
|
108
|
+
The `superkernel` command launches a notebook adapter; it is not a Gateway or
|
|
109
|
+
infrastructure-management CLI.
|
|
110
|
+
|
|
111
|
+
## Security
|
|
112
|
+
|
|
113
|
+
SuperKernel reads authentication from a client-managed local file immediately
|
|
114
|
+
before each remote request. Credentials are not embedded in the kernelspec,
|
|
115
|
+
stored by this package, or passed directly on the process command line. The
|
|
116
|
+
runtime fails closed when its authentication file is missing or invalid.
|
|
117
|
+
It validates the version-1 session metadata, expiry, and Gateway binding before
|
|
118
|
+
every request; renewing the private file takes effect without restarting it.
|
|
119
|
+
|
|
120
|
+
## Tests
|
|
121
|
+
|
|
122
|
+
Run `python -m pytest -q superkernel-adapter/tests` from the repository root with
|
|
123
|
+
the runtime and pytest installed. Tests use temporary private state and do not
|
|
124
|
+
read or modify saved user credentials.
|
|
125
|
+
|
|
126
|
+
## Project status
|
|
127
|
+
|
|
128
|
+
Version 0.9.7 is the first renamed adapter build. Publishing is a separate
|
|
129
|
+
release step. The execution and shared-state protocols remain unchanged from
|
|
130
|
+
the 0.9.6 beta backend; the integration contract may still evolve before 1.0.
|
|
131
|
+
|
|
132
|
+
Learn more at [superkernel.leoustc.com](https://superkernel.leoustc.com).
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
superkernel_adapter/__init__.py,sha256=9ZQVN6RDQM7IJABn-jgarbY_vYy6YxjQhNG_geX02S0,642
|
|
2
|
+
superkernel_adapter/kernel.py,sha256=xitc67XtoEL7d9D4DC3vnnbqjnWT2-q1rwe2cEtp2XI,26699
|
|
3
|
+
superkernel_adapter/launcher.py,sha256=b8lADQ627ngrp0SGvgomPJcostWtpjxhTjeeH_1mEss,1425
|
|
4
|
+
superkernel_adapter/logfile.py,sha256=GS4ESQn_vILN3lyE0FLKmeJHX3ORBcjEeWXPvfdp7lE,910
|
|
5
|
+
superkernel_adapter/schema.py,sha256=vHBzlIMlo-1Hq3KckhbS4Suc9oHPcc7sle7Fk34x0z8,5501
|
|
6
|
+
superkernel_adapter/state.py,sha256=69rr4cE0GnPUWg6E4HGM-T7T3RI-UyDceLm2xwYbXhk,7801
|
|
7
|
+
superkernel_adapter-0.9.7.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
|
|
8
|
+
superkernel_adapter-0.9.7.dist-info/METADATA,sha256=XU0rbXu-5vZiDsDcZNaCkS6oSXnzPC0g4ggsWXVF1xo,5427
|
|
9
|
+
superkernel_adapter-0.9.7.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
10
|
+
superkernel_adapter-0.9.7.dist-info/entry_points.txt,sha256=CT3VPKCUTJhQpRhiU2qSOQM9PpAMOPt_IDvSoyWKhYs,64
|
|
11
|
+
superkernel_adapter-0.9.7.dist-info/top_level.txt,sha256=aOEv6yeAB-D7SLuGoWmfi8b541uZcyTW-wARA-P561E,20
|
|
12
|
+
superkernel_adapter-0.9.7.dist-info/RECORD,,
|