levier-runtime 0.1.0__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.
@@ -0,0 +1,57 @@
1
+ """Levier Runtime SDK.
2
+
3
+ A runtime author defines one `run(ctx)` function and gives it to `Runtime`:
4
+
5
+ from levier_runtime import Runtime, RunContext
6
+
7
+ async def run(ctx: RunContext) -> str:
8
+ await ctx.reply("hello")
9
+ return "completed"
10
+
11
+ Runtime.from_config("runtime.yaml").run(run)
12
+
13
+ The SDK owns the RuntimeChannel and protocol. Model, tools, MCP, and checkpoint
14
+ are optional capabilities exposed through `RunContext`.
15
+
16
+ Copyright 2026 The Levier Authors.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ __version__ = "0.1.0"
22
+
23
+ from .config import ConfigError, MiddlewareConfig, RuntimeConfig, load_runtime_config
24
+ from .context import RunContext, RuntimeUsageError
25
+ from .runtime import Runtime, RunFunction
26
+ from .toolbox import Tool, Toolbox
27
+ from .types import (
28
+ McpBinding,
29
+ Message,
30
+ ModelConfig,
31
+ Timeouts,
32
+ ToolResult,
33
+ ToolSpec,
34
+ )
35
+
36
+ # The short name runtime authors see in the docs.
37
+ Context = RunContext
38
+
39
+ __all__ = [
40
+ "ConfigError",
41
+ "Context",
42
+ "McpBinding",
43
+ "Message",
44
+ "MiddlewareConfig",
45
+ "ModelConfig",
46
+ "RunContext",
47
+ "RunFunction",
48
+ "Runtime",
49
+ "RuntimeConfig",
50
+ "RuntimeUsageError",
51
+ "Timeouts",
52
+ "Tool",
53
+ "ToolResult",
54
+ "ToolSpec",
55
+ "Toolbox",
56
+ "load_runtime_config",
57
+ ]
@@ -0,0 +1,5 @@
1
+ """RuntimeChannel client package."""
2
+
3
+ from .client import ChannelClient, ChannelConfig
4
+
5
+ __all__ = ["ChannelClient", "ChannelConfig"]
@@ -0,0 +1,317 @@
1
+ """Levier — RuntimeChannel gRPC client.
2
+
3
+ Maintains one bidirectional stream, sends Hello/heartbeats, dispatches
4
+ inbound envelopes, and reconnects with exponential backoff.
5
+
6
+ Copyright 2026 The Levier Authors.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import asyncio
12
+ import inspect
13
+ import logging
14
+ import random
15
+ import time
16
+ from dataclasses import dataclass, field
17
+ from typing import Awaitable, Callable, Sequence
18
+
19
+ import grpc
20
+ from middleware.runtime.v1 import runtime_pb2, runtime_pb2_grpc
21
+
22
+ from .envelope import new_envelope, response_envelope
23
+ from ..ids import new_ulid
24
+
25
+ MessageHandler = Callable[[runtime_pb2.Envelope], Awaitable[None] | None]
26
+ RunningRunsProvider = Callable[[], Sequence[tuple[str, int]]]
27
+ RunningCountProvider = Callable[[], int]
28
+
29
+
30
+ @dataclass
31
+ class ChannelConfig:
32
+ """Connection and heartbeat settings."""
33
+
34
+ address: str
35
+ daemon_id: str
36
+ runtime_name: str
37
+ auth_token: str
38
+ runtime_type: str = "normal"
39
+ max_concurrent_runs: int = 4
40
+ version: str = "0.1.0"
41
+ labels: dict[str, str] = field(default_factory=dict)
42
+ tls: bool = False
43
+ heartbeat_interval: float = 10.0
44
+ reconnect_initial: float = 1.0
45
+ reconnect_max: float = 30.0
46
+ reconnect_stable_after: float = 5.0
47
+ hello_timeout: float = 3.0
48
+
49
+
50
+ class ChannelClient:
51
+ """Owns one RuntimeChannel stream and its reconnect loop."""
52
+
53
+ def __init__(
54
+ self,
55
+ config: ChannelConfig,
56
+ on_message: MessageHandler | None = None,
57
+ running_runs: RunningRunsProvider | None = None,
58
+ running_count: RunningCountProvider | None = None,
59
+ logger: logging.Logger | None = None,
60
+ ) -> None:
61
+ self.config = config
62
+ self.on_message = on_message
63
+ self.running_runs = running_runs or (lambda: [])
64
+ self.running_count = running_count or (lambda: 0)
65
+ self.logger = logger or logging.getLogger("levier_runtime.channel")
66
+
67
+ self._control: asyncio.Queue[runtime_pb2.Envelope] = asyncio.Queue(maxsize=64)
68
+ self._outbound: asyncio.Queue[runtime_pb2.Envelope] = asyncio.Queue(maxsize=256)
69
+ self._wakeup = asyncio.Event()
70
+ self._connected = asyncio.Event()
71
+ self._stopped = asyncio.Event()
72
+ self._runner: asyncio.Task[None] | None = None
73
+ self._call: Any = None
74
+ self._pending: dict[str, asyncio.Future[runtime_pb2.Envelope]] = {}
75
+ self._last_reconnect_delay = 0.0
76
+
77
+ @property
78
+ def connected(self) -> bool:
79
+ """Whether the current stream has completed Hello."""
80
+ return self._connected.is_set()
81
+
82
+ async def start(self) -> None:
83
+ """Start the reconnect/read loop."""
84
+ if self._runner is not None:
85
+ return
86
+ self._runner = asyncio.create_task(self._run(), name="runtime-channel")
87
+
88
+ async def wait_connected(self, timeout: float | None = None) -> None:
89
+ """Wait until the stream is connected."""
90
+ await asyncio.wait_for(self._connected.wait(), timeout)
91
+
92
+ async def send(self, envelope: runtime_pb2.Envelope) -> None:
93
+ """Queue an outbound envelope for the current stream.
94
+
95
+ Heartbeats, Acks, tool results and errors use a small control queue so
96
+ a full event queue cannot make a healthy daemon look offline.
97
+ """
98
+ if self._stopped.is_set():
99
+ raise RuntimeError("channel client is stopped")
100
+ if _is_control_envelope(envelope):
101
+ await self._control.put(envelope)
102
+ else:
103
+ await self._outbound.put(envelope)
104
+ self._wakeup.set()
105
+
106
+ async def send_response(self, request: runtime_pb2.Envelope, payload: Any, field: str) -> None:
107
+ """Queue a response correlated to request.msg_id."""
108
+ await self.send(response_envelope(request, payload, field))
109
+
110
+ async def request(
111
+ self,
112
+ payload: Any,
113
+ field: str,
114
+ *,
115
+ run_id: str = "",
116
+ attempt: int = 0,
117
+ lease_epoch: int = 0,
118
+ timeout: float = 30.0,
119
+ ) -> runtime_pb2.Envelope:
120
+ """Send one request and wait for its correlated response envelope."""
121
+ envelope = new_envelope(
122
+ payload,
123
+ field,
124
+ run_id=run_id,
125
+ attempt=attempt,
126
+ lease_epoch=lease_epoch,
127
+ )
128
+ loop = asyncio.get_running_loop()
129
+ future: asyncio.Future[runtime_pb2.Envelope] = loop.create_future()
130
+ self._pending[envelope.msg_id] = future
131
+ try:
132
+ await self.send(envelope)
133
+ return await asyncio.wait_for(future, timeout)
134
+ finally:
135
+ self._pending.pop(envelope.msg_id, None)
136
+
137
+ async def stop(self) -> None:
138
+ """Stop reconnecting and close the stream."""
139
+ self._stopped.set()
140
+ if self._call is not None:
141
+ self._call.cancel()
142
+ if self._runner is not None:
143
+ self._runner.cancel()
144
+ try:
145
+ await self._runner
146
+ except asyncio.CancelledError:
147
+ pass
148
+ self._runner = None
149
+ self._connected.clear()
150
+
151
+ async def _run(self) -> None:
152
+ delay = self.config.reconnect_initial
153
+ while not self._stopped.is_set():
154
+ started = time.monotonic()
155
+ connected = False
156
+ try:
157
+ connected = await self._session()
158
+ except asyncio.CancelledError:
159
+ raise
160
+ except Exception as exc: # keep the daemon alive across transport errors
161
+ self.logger.warning("runtime channel session ended", extra={
162
+ "daemon_id": self.config.daemon_id,
163
+ "error": str(exc),
164
+ })
165
+ duration = time.monotonic() - started
166
+ if connected and duration >= self.config.reconnect_stable_after:
167
+ delay = self.config.reconnect_initial
168
+ if self._stopped.is_set():
169
+ return
170
+ sleep_for = min(delay, self.config.reconnect_max)
171
+ sleep_for *= random.uniform(0.8, 1.2)
172
+ self._last_reconnect_delay = sleep_for
173
+ self.logger.info("runtime channel reconnecting", extra={
174
+ "daemon_id": self.config.daemon_id,
175
+ "delay_seconds": round(sleep_for, 3),
176
+ "session_seconds": round(duration, 3),
177
+ })
178
+ await asyncio.sleep(sleep_for)
179
+ delay = min(delay * 2, self.config.reconnect_max)
180
+
181
+ async def _session(self) -> bool:
182
+ channel = self._make_channel()
183
+ connected = False
184
+ try:
185
+ await asyncio.wait_for(channel.channel_ready(), self.config.hello_timeout)
186
+ self._drain_control()
187
+ stub = runtime_pb2_grpc.RuntimeServiceStub(channel)
188
+ call = stub.Channel()
189
+ self._call = call
190
+ await call.write(self._hello())
191
+ self._connected.set()
192
+ connected = True
193
+
194
+ writer = asyncio.create_task(self._writer(call), name="runtime-writer")
195
+ heartbeat = asyncio.create_task(self._heartbeat(), name="runtime-heartbeat")
196
+ try:
197
+ async for envelope in call:
198
+ await self._dispatch(envelope)
199
+ finally:
200
+ writer.cancel()
201
+ heartbeat.cancel()
202
+ await asyncio.gather(writer, heartbeat, return_exceptions=True)
203
+ self._connected.clear()
204
+ self._call = None
205
+ self._fail_pending(ConnectionError("runtime channel disconnected"))
206
+ finally:
207
+ await channel.close()
208
+ self._connected.clear()
209
+ return connected
210
+
211
+ def _make_channel(self) -> grpc.aio.Channel:
212
+ if self.config.tls:
213
+ return grpc.aio.secure_channel(
214
+ self.config.address,
215
+ grpc.ssl_channel_credentials(),
216
+ )
217
+ return grpc.aio.insecure_channel(self.config.address)
218
+
219
+ def _hello(self) -> runtime_pb2.Envelope:
220
+ running = [
221
+ runtime_pb2.RunningRun(run_id=run_id, lease_epoch=lease_epoch)
222
+ for run_id, lease_epoch in self.running_runs()
223
+ ]
224
+ hello = runtime_pb2.Hello(
225
+ daemon_id=self.config.daemon_id,
226
+ runtime_name=self.config.runtime_name,
227
+ auth_token=self.config.auth_token,
228
+ runtime_type=_runtime_type(self.config.runtime_type),
229
+ max_concurrent_runs=self.config.max_concurrent_runs,
230
+ version=self.config.version,
231
+ labels=self.config.labels,
232
+ running_runs=running,
233
+ )
234
+ return new_envelope(hello, "hello")
235
+
236
+ async def _writer(self, call: Any) -> None:
237
+ while True:
238
+ envelope = self._take_next()
239
+ if envelope is None:
240
+ self._wakeup.clear()
241
+ envelope = self._take_next()
242
+ if envelope is None:
243
+ await self._wakeup.wait()
244
+ continue
245
+ await call.write(envelope)
246
+
247
+ def _take_next(self) -> runtime_pb2.Envelope | None:
248
+ try:
249
+ return self._control.get_nowait()
250
+ except asyncio.QueueEmpty:
251
+ pass
252
+ try:
253
+ return self._outbound.get_nowait()
254
+ except asyncio.QueueEmpty:
255
+ return None
256
+
257
+ def _drain_control(self) -> None:
258
+ while True:
259
+ try:
260
+ self._control.get_nowait()
261
+ except asyncio.QueueEmpty:
262
+ return
263
+
264
+ async def _heartbeat(self) -> None:
265
+ while True:
266
+ await asyncio.sleep(self.config.heartbeat_interval)
267
+ heartbeat = runtime_pb2.Heartbeat(
268
+ running_count=self.running_count(),
269
+ cpu_load=0.0,
270
+ mem_mb=0.0,
271
+ )
272
+ await self.send(new_envelope(heartbeat, "heartbeat"))
273
+
274
+ async def _dispatch(self, envelope: runtime_pb2.Envelope) -> None:
275
+ if envelope.WhichOneof("payload") == "tool_call_result":
276
+ future = self._pending.get(envelope.correlation_id)
277
+ if future is not None and not future.done():
278
+ future.set_result(envelope)
279
+ return
280
+ if self.on_message is None:
281
+ return
282
+ try:
283
+ result = self.on_message(envelope)
284
+ if inspect.isawaitable(result):
285
+ await result
286
+ except Exception as exc:
287
+ self.logger.error("runtime channel handler failed", extra={
288
+ "daemon_id": self.config.daemon_id,
289
+ "error": str(exc),
290
+ })
291
+
292
+
293
+ def _fail_pending(self, exc: BaseException) -> None:
294
+ pending = list(self._pending.values())
295
+ self._pending.clear()
296
+ for future in pending:
297
+ if not future.done():
298
+ future.set_exception(exc)
299
+
300
+
301
+ def _is_control_envelope(envelope: runtime_pb2.Envelope) -> bool:
302
+ return envelope.WhichOneof("payload") in {
303
+ "hello",
304
+ "heartbeat",
305
+ "task_ack",
306
+ "tool_call_result",
307
+ "error",
308
+ }
309
+
310
+
311
+ def _runtime_type(value: str) -> int:
312
+ mapping = {
313
+ "normal": runtime_pb2.RuntimeType.NORMAL,
314
+ "sandbox": runtime_pb2.RuntimeType.SANDBOX,
315
+ "longterm": runtime_pb2.RuntimeType.LONGTERM,
316
+ }
317
+ return mapping.get(value, runtime_pb2.RuntimeType.NORMAL)
@@ -0,0 +1,57 @@
1
+ """Levier — RuntimeChannel envelope helpers.
2
+
3
+ Builds envelopes with ULID message IDs and response correlation.
4
+
5
+ Copyright 2026 The Levier Authors.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import time
11
+ from typing import Any
12
+
13
+ from middleware.runtime.v1 import runtime_pb2
14
+ from ..ids import new_ulid
15
+
16
+
17
+ def new_envelope(
18
+ payload: Any,
19
+ field: str,
20
+ *,
21
+ msg_id: str | None = None,
22
+ ts_ms: int | None = None,
23
+ run_id: str = "",
24
+ attempt: int = 0,
25
+ lease_epoch: int = 0,
26
+ correlation_id: str = "",
27
+ ) -> runtime_pb2.Envelope:
28
+ """Build an envelope and copy payload into its oneof field."""
29
+ envelope = runtime_pb2.Envelope(
30
+ msg_id=msg_id or new_ulid(),
31
+ correlation_id=correlation_id,
32
+ run_id=run_id,
33
+ ts_ms=int(time.time() * 1000) if ts_ms is None else ts_ms,
34
+ attempt=attempt,
35
+ lease_epoch=lease_epoch,
36
+ )
37
+ target = getattr(envelope, field)
38
+ target.CopyFrom(payload)
39
+ return envelope
40
+
41
+
42
+ def response_envelope(
43
+ request: runtime_pb2.Envelope,
44
+ payload: Any,
45
+ field: str,
46
+ **kwargs: Any,
47
+ ) -> runtime_pb2.Envelope:
48
+ """Build a response correlated to request.msg_id."""
49
+ return new_envelope(
50
+ payload,
51
+ field,
52
+ run_id=request.run_id,
53
+ attempt=request.attempt,
54
+ lease_epoch=request.lease_epoch,
55
+ correlation_id=request.msg_id,
56
+ **kwargs,
57
+ )
levier_runtime/cli.py ADDED
@@ -0,0 +1,116 @@
1
+ """Small CLI shell shared by built-in Levier runtimes.
2
+
3
+ It handles configuration loading, validation, logging, and the common runtime
4
+ flags. Runtime-specific entry points only provide their async serve function
5
+ and any extra options.
6
+
7
+ Copyright 2026 The Levier Authors.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import asyncio
14
+ import logging
15
+ import os
16
+ import sys
17
+ from pathlib import Path
18
+ from typing import Awaitable, Callable, Sequence
19
+
20
+ from .profile import default_runtime_config
21
+ from .runtime import Runtime
22
+
23
+ ServeFunction = Callable[[Runtime, argparse.Namespace], Awaitable[None]]
24
+ ExtraArguments = Callable[[argparse.ArgumentParser], None]
25
+ PrintConfigExtra = Callable[[Runtime, argparse.Namespace], Sequence[str]]
26
+
27
+
28
+ def run_cli(
29
+ *,
30
+ prog: str,
31
+ version: str,
32
+ default_config: str | Path,
33
+ serve: ServeFunction,
34
+ config_env: Sequence[str] = (),
35
+ add_arguments: ExtraArguments | None = None,
36
+ print_config_extra: PrintConfigExtra | None = None,
37
+ argv: Sequence[str] | None = None,
38
+ ) -> int:
39
+ """Parse common runtime flags and serve until shutdown."""
40
+ parser = argparse.ArgumentParser(prog=prog)
41
+ default = (
42
+ _first_env(config_env)
43
+ or os.environ.get("LEVIER_RUNTIME_CONFIG")
44
+ or default_runtime_config()
45
+ or str(default_config)
46
+ )
47
+ parser.add_argument(
48
+ "--config",
49
+ default=default,
50
+ help="path to runtime YAML configuration (or LEVIER_RUNTIME_CONFIG / levier setup)",
51
+ )
52
+ parser.add_argument("--check", action="store_true", help="validate configuration")
53
+ parser.add_argument("--print-config", action="store_true", help="print redacted configuration")
54
+ parser.add_argument("--version", action="store_true", help="print version")
55
+ parser.add_argument("--log-level", default="", help="override log level")
56
+ if add_arguments is not None:
57
+ add_arguments(parser)
58
+ args = parser.parse_args(argv)
59
+
60
+ if args.version:
61
+ print(f"{prog} {version}")
62
+ return 0
63
+
64
+ if getattr(args, "log_level", ""):
65
+ os.environ["LEVIER_RUNTIME_LOG_LEVEL"] = args.log_level
66
+ try:
67
+ runtime = Runtime.from_config(args.config)
68
+ except Exception as exc: # configuration must produce a clean CLI error
69
+ print(f"{prog} config error: {exc}", file=sys.stderr)
70
+ return 1
71
+
72
+ level = getattr(logging, runtime.config.log_level.upper(), logging.INFO)
73
+ logging.basicConfig(level=level)
74
+ if args.check:
75
+ print(f"runtime {runtime.config.runtime_name} / {runtime.config.instance_id}")
76
+ return 0
77
+ if args.print_config:
78
+ _print_config(runtime, args, print_config_extra)
79
+ return 0
80
+
81
+ try:
82
+ asyncio.run(serve(runtime, args))
83
+ except KeyboardInterrupt:
84
+ pass
85
+ return 0
86
+
87
+
88
+ def _print_config(
89
+ runtime: Runtime,
90
+ args: argparse.Namespace,
91
+ extra: PrintConfigExtra | None,
92
+ ) -> None:
93
+ config = runtime.config
94
+ print(f"runtime: {config.runtime_name}")
95
+ print(f"instance_id: {config.instance_id}")
96
+ print(f"runtime_type: {config.runtime_type}")
97
+ print(f"middleware_address: {config.middleware.address}")
98
+ print(f"middleware_tls: {str(config.middleware.tls).lower()}")
99
+ print(
100
+ "middleware_auth_token: ***"
101
+ if config.middleware.auth_token
102
+ else "middleware_auth_token: (empty)"
103
+ )
104
+ print(f"max_concurrent_runs: {config.max_concurrent_runs}")
105
+ print(f"log_level: {config.log_level}")
106
+ if extra is not None:
107
+ for line in extra(runtime, args):
108
+ print(line)
109
+
110
+
111
+ def _first_env(names: Sequence[str]) -> str:
112
+ for name in names:
113
+ value = os.environ.get(name)
114
+ if value:
115
+ return value
116
+ return ""