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,193 @@
1
+ """Levier — longterm checkpoint encoding.
2
+
3
+ Checkpoint payloads are opaque to middleware. The optional React helper owns
4
+ the schema, versioning, and restore compatibility checks.
5
+
6
+ Copyright 2026 The Levier Authors.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ from dataclasses import dataclass, field
13
+ from datetime import datetime, timezone
14
+ from typing import Any
15
+
16
+ from levier_runtime.llm.base import Message, ToolCall
17
+
18
+ CHECKPOINT_VERSION = 1
19
+
20
+
21
+ class CheckpointError(ValueError):
22
+ """Raised when checkpoint bytes are invalid or unsupported."""
23
+
24
+
25
+ @dataclass
26
+ class CheckpointState:
27
+ """React-Runtime-owned longterm state."""
28
+
29
+ session_id: str
30
+ run_id: str
31
+ attempt: int
32
+ runtime_name: str
33
+ step: int = 0
34
+ messages: list[Message] = field(default_factory=list)
35
+ last_event_attempt: int = 0
36
+ last_event_seq: int = 0
37
+ created_at: str = ""
38
+ version: int = CHECKPOINT_VERSION
39
+
40
+ def encode(self) -> bytes:
41
+ """Encode the checkpoint as UTF-8 JSON."""
42
+ payload = {
43
+ "version": self.version,
44
+ "session_id": self.session_id,
45
+ "run_id": self.run_id,
46
+ "attempt": self.attempt,
47
+ "runtime_name": self.runtime_name,
48
+ "step": self.step,
49
+ "messages": [_message_to_dict(message) for message in self.messages],
50
+ "last_event_attempt": self.last_event_attempt,
51
+ "last_event_seq": self.last_event_seq,
52
+ "created_at": self.created_at or _now(),
53
+ }
54
+ return json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
55
+
56
+ @classmethod
57
+ def decode(cls, data: bytes) -> "CheckpointState":
58
+ """Decode checkpoint bytes."""
59
+ if not data:
60
+ raise CheckpointError("checkpoint is empty")
61
+ try:
62
+ payload = json.loads(data.decode("utf-8"))
63
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
64
+ raise CheckpointError("checkpoint is not valid JSON") from exc
65
+ if not isinstance(payload, dict):
66
+ raise CheckpointError("checkpoint must be an object")
67
+ version = _int(payload.get("version"), "version")
68
+ if version != CHECKPOINT_VERSION:
69
+ raise CheckpointError(f"unsupported checkpoint version {version}")
70
+
71
+ session_id = _str(payload.get("session_id"), "session_id", allow_empty=False)
72
+ run_id = _str(payload.get("run_id"), "run_id", allow_empty=False)
73
+ runtime_name = _str(payload.get("runtime_name"), "runtime_name", allow_empty=False)
74
+ attempt = _int(payload.get("attempt"), "attempt", minimum=1)
75
+ step = _int(payload.get("step"), "step", minimum=0)
76
+ last_event_attempt = _int(payload.get("last_event_attempt"), "last_event_attempt", minimum=0)
77
+ last_event_seq = _int(payload.get("last_event_seq"), "last_event_seq", minimum=0)
78
+ created_at = _str(payload.get("created_at"), "created_at", allow_empty=True)
79
+
80
+ raw_messages = payload.get("messages")
81
+ if not isinstance(raw_messages, list):
82
+ raise CheckpointError("messages must be a list")
83
+ messages = [_message_from_dict(item) for item in raw_messages]
84
+ return cls(
85
+ session_id=session_id,
86
+ run_id=run_id,
87
+ attempt=attempt,
88
+ runtime_name=runtime_name,
89
+ step=step,
90
+ messages=messages,
91
+ last_event_attempt=last_event_attempt,
92
+ last_event_seq=last_event_seq,
93
+ created_at=created_at,
94
+ version=version,
95
+ )
96
+
97
+
98
+ def capture(
99
+ *,
100
+ session_id: str,
101
+ run_id: str,
102
+ attempt: int,
103
+ runtime_name: str,
104
+ step: int,
105
+ messages: list[Message],
106
+ last_event_seq: int,
107
+ last_event_attempt: int | None = None,
108
+ ) -> CheckpointState:
109
+ """Capture a checkpoint at a safe point."""
110
+ return CheckpointState(
111
+ session_id=session_id,
112
+ run_id=run_id,
113
+ attempt=attempt,
114
+ runtime_name=runtime_name,
115
+ step=step,
116
+ messages=list(messages),
117
+ last_event_attempt=attempt if last_event_attempt is None else last_event_attempt,
118
+ last_event_seq=last_event_seq,
119
+ created_at=_now(),
120
+ )
121
+
122
+
123
+ def _message_to_dict(message: Message) -> dict[str, Any]:
124
+ payload: dict[str, Any] = {
125
+ "role": message.role,
126
+ "content": message.content,
127
+ }
128
+ if message.name:
129
+ payload["name"] = message.name
130
+ if message.tool_call_id:
131
+ payload["tool_call_id"] = message.tool_call_id
132
+ if message.tool_calls:
133
+ payload["tool_calls"] = [
134
+ {
135
+ "call_id": call.call_id,
136
+ "name": call.name,
137
+ "arguments_json": call.arguments_json,
138
+ }
139
+ for call in message.tool_calls
140
+ ]
141
+ return payload
142
+
143
+
144
+ def _message_from_dict(value: Any) -> Message:
145
+ if not isinstance(value, dict):
146
+ raise CheckpointError("message must be an object")
147
+ role = _str(value.get("role"), "message.role", allow_empty=False)
148
+ content = _str(value.get("content"), "message.content", allow_empty=True)
149
+ name = _str(value.get("name"), "message.name", allow_empty=True)
150
+ tool_call_id = _str(value.get("tool_call_id"), "message.tool_call_id", allow_empty=True)
151
+ raw_calls = value.get("tool_calls") or []
152
+ if not isinstance(raw_calls, list):
153
+ raise CheckpointError("message.tool_calls must be a list")
154
+ calls = tuple(_tool_call_from_dict(item) for item in raw_calls)
155
+ return Message(
156
+ role=role,
157
+ content=content,
158
+ name=name,
159
+ tool_call_id=tool_call_id,
160
+ tool_calls=calls,
161
+ )
162
+
163
+
164
+ def _tool_call_from_dict(value: Any) -> ToolCall:
165
+ if not isinstance(value, dict):
166
+ raise CheckpointError("tool call must be an object")
167
+ return ToolCall(
168
+ call_id=_str(value.get("call_id"), "tool_call.call_id", allow_empty=True),
169
+ name=_str(value.get("name"), "tool_call.name", allow_empty=False),
170
+ arguments_json=_str(value.get("arguments_json"), "tool_call.arguments_json", allow_empty=True),
171
+ )
172
+
173
+
174
+ def _str(value: Any, field_name: str, *, allow_empty: bool) -> str:
175
+ if value is None and allow_empty:
176
+ return ""
177
+ if not isinstance(value, str):
178
+ raise CheckpointError(f"{field_name} must be a string")
179
+ if not allow_empty and not value:
180
+ raise CheckpointError(f"{field_name} is required")
181
+ return value
182
+
183
+
184
+ def _int(value: Any, field_name: str, *, minimum: int | None = None) -> int:
185
+ if isinstance(value, bool) or not isinstance(value, int):
186
+ raise CheckpointError(f"{field_name} must be an integer")
187
+ if minimum is not None and value < minimum:
188
+ raise CheckpointError(f"{field_name} must be >= {minimum}")
189
+ return value
190
+
191
+
192
+ def _now() -> str:
193
+ return datetime.now(tz=timezone.utc).isoformat()
@@ -0,0 +1,139 @@
1
+ """Runtime process lifecycle.
2
+
3
+ The public entry point is `Runtime.from_config(...).run(your_run_function)`.
4
+ The SDK owns channel setup, reconnects, heartbeats, acknowledgements, event
5
+ sequencing, cancellation, and graceful shutdown.
6
+
7
+ Copyright 2026 The Levier Authors.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ import logging
14
+ import signal
15
+ from pathlib import Path
16
+ from typing import Awaitable, Callable
17
+
18
+ from . import __version__
19
+ from .channel.client import ChannelClient, ChannelConfig
20
+ from .config import RuntimeConfig, load_runtime_config
21
+ from .context import RunContext
22
+ from .manager import ManagerConfig, RunManager
23
+
24
+ RunFunction = Callable[[RunContext], Awaitable[str]]
25
+
26
+
27
+ class Runtime:
28
+ """One runtime process serving one `runtime_name`."""
29
+
30
+ def __init__(self, config: RuntimeConfig | None = None, *, logger: logging.Logger | None = None) -> None:
31
+ self.config = config or load_runtime_config()
32
+ self.logger = logger or logging.getLogger("levier_runtime")
33
+ self._stop_event: asyncio.Event | None = None
34
+
35
+ @classmethod
36
+ def from_config(
37
+ cls,
38
+ path: str | Path | None = None,
39
+ *,
40
+ environ: dict[str, str] | None = None,
41
+ logger: logging.Logger | None = None,
42
+ ) -> "Runtime":
43
+ """Build a runtime from `runtime.yaml`, the user profile, or defaults."""
44
+ return cls(load_runtime_config(path, environ=environ), logger=logger)
45
+
46
+ @classmethod
47
+ def start(
48
+ cls,
49
+ run: RunFunction,
50
+ *,
51
+ config: RuntimeConfig | str | Path | None = None,
52
+ environ: dict[str, str] | None = None,
53
+ handle_signals: bool = True,
54
+ ) -> int:
55
+ """Load defaults (no YAML required) and serve one `run(ctx)`."""
56
+ if isinstance(config, RuntimeConfig):
57
+ runtime = cls(config)
58
+ else:
59
+ runtime = cls.from_config(config, environ=environ)
60
+ return runtime.run(run, handle_signals=handle_signals)
61
+
62
+ def run(self, run: RunFunction, *, handle_signals: bool = True) -> int:
63
+ """Run until SIGINT/SIGTERM or `stop()` is called."""
64
+ _configure_logging(self.config.log_level)
65
+ try:
66
+ asyncio.run(self.serve(run, handle_signals=handle_signals))
67
+ except KeyboardInterrupt:
68
+ pass
69
+ return 0
70
+
71
+ async def serve(self, run: RunFunction, *, handle_signals: bool = True) -> None:
72
+ """Async variant used by tests and embedding callers."""
73
+ channel = ChannelClient(
74
+ ChannelConfig(
75
+ address=self.config.middleware.address,
76
+ daemon_id=self.config.instance_id,
77
+ runtime_name=self.config.runtime_name,
78
+ auth_token=self.config.middleware.auth_token,
79
+ runtime_type=self.config.runtime_type,
80
+ max_concurrent_runs=self.config.max_concurrent_runs,
81
+ version=__version__,
82
+ labels=dict(self.config.labels),
83
+ tls=self.config.middleware.tls,
84
+ ),
85
+ logger=logging.getLogger("levier_runtime.channel"),
86
+ )
87
+ manager = RunManager(
88
+ channel,
89
+ ManagerConfig(
90
+ runtime_name=self.config.runtime_name,
91
+ max_concurrent_runs=self.config.max_concurrent_runs,
92
+ ),
93
+ run,
94
+ logger=logging.getLogger("levier_runtime.manager"),
95
+ )
96
+ channel.on_message = manager.handle
97
+ channel.running_runs = manager.running_runs
98
+ channel.running_count = manager.running_count
99
+
100
+ self._stop_event = asyncio.Event()
101
+ removers = _install_signal_handlers(self._stop_event) if handle_signals else []
102
+ self.logger.info(
103
+ "runtime starting name=%s instance=%s",
104
+ self.config.runtime_name,
105
+ self.config.instance_id,
106
+ )
107
+ await channel.start()
108
+ try:
109
+ await self._stop_event.wait()
110
+ finally:
111
+ for remove in removers:
112
+ remove()
113
+ await manager.close()
114
+ await channel.stop()
115
+ self.logger.info("runtime stopped name=%s", self.config.runtime_name)
116
+
117
+ def stop(self) -> None:
118
+ """Request a graceful stop."""
119
+ if self._stop_event is not None:
120
+ self._stop_event.set()
121
+
122
+
123
+ def _install_signal_handlers(stop: asyncio.Event) -> list[Callable[[], None]]:
124
+ loop = asyncio.get_running_loop()
125
+ removers: list[Callable[[], None]] = []
126
+ for signum in (signal.SIGINT, signal.SIGTERM):
127
+ try:
128
+ loop.add_signal_handler(signum, stop.set)
129
+ except (NotImplementedError, RuntimeError):
130
+ continue
131
+ removers.append(lambda signum=signum: loop.remove_signal_handler(signum))
132
+ return removers
133
+
134
+
135
+ def _configure_logging(level: str) -> None:
136
+ logging.basicConfig(
137
+ level=level.upper(),
138
+ format="%(asctime)s %(levelname)s %(name)s %(message)s",
139
+ )
@@ -0,0 +1,261 @@
1
+ """One object that makes local and MCP tools look the same.
2
+
3
+ Runtime authors do not need to know whether a capability is a local App tool
4
+ or an MCP tool. ``await ctx.toolbox()`` returns a sequence of callable tools,
5
+ model-facing specs, and one dispatch method.
6
+
7
+ Copyright 2026 The Levier Authors.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import time
14
+ from dataclasses import dataclass, field
15
+ from typing import Any, Awaitable, Callable, Iterator, Mapping, Sequence
16
+
17
+ from .ids import new_ulid
18
+ from .mcp import McpRuntimeClient, McpRuntimeError
19
+ from .types import McpBinding, ToolResult, ToolSpec
20
+
21
+
22
+ _Caller = Callable[[str], Awaitable[ToolResult]]
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class Tool:
27
+ """One tool with a uniform async call interface."""
28
+
29
+ name: str
30
+ description: str
31
+ schema_json: str
32
+ scope: str
33
+ _caller: _Caller = field(repr=False, compare=False)
34
+
35
+ async def call(self, arguments: Mapping[str, Any] | str | None = None) -> ToolResult:
36
+ """Call this tool with a mapping or a JSON object string."""
37
+ if isinstance(arguments, Mapping):
38
+ payload = json.dumps(arguments, ensure_ascii=False, separators=(",", ":"))
39
+ elif arguments is None:
40
+ payload = "{}"
41
+ elif isinstance(arguments, str):
42
+ payload = arguments
43
+ else:
44
+ raise TypeError("tool arguments must be a mapping or JSON string")
45
+ return await self._caller(payload)
46
+
47
+
48
+ class Toolbox(Sequence[Tool]):
49
+ """All tools visible to one Run, local and MCP, with one dispatcher."""
50
+
51
+ def __init__(
52
+ self,
53
+ tools: Sequence[Tool],
54
+ *,
55
+ mcp: McpRuntimeClient | None = None,
56
+ sessions: Sequence[str] = (),
57
+ logger: Any = None,
58
+ ) -> None:
59
+ self._tools = list(tools)
60
+ self._by_name = {tool.name: tool for tool in self._tools}
61
+ self._mcp = mcp
62
+ self._sessions = list(sessions)
63
+ self._logger = logger
64
+
65
+ @classmethod
66
+ async def open(cls, ctx: "Any") -> "Toolbox":
67
+ """Build the toolbox for one ``RunContext``."""
68
+ tools: list[Tool] = []
69
+ for spec in ctx.tools:
70
+ tools.append(_local_tool(ctx, spec))
71
+
72
+ mcp_client: McpRuntimeClient | None = None
73
+ sessions: list[str] = []
74
+ if ctx.mcp_bindings:
75
+ socket_path = _mcp_socket()
76
+ if not socket_path:
77
+ ctx.logger.warning(
78
+ "MCP bindings were provided but no MCP runtime socket is configured"
79
+ )
80
+ else:
81
+ mcp_client = McpRuntimeClient(socket_path)
82
+ for binding in ctx.mcp_bindings:
83
+ session_id, mcp_tools = await _open_mcp(ctx, mcp_client, binding)
84
+ if session_id:
85
+ sessions.append(session_id)
86
+ tools.extend(mcp_tools)
87
+ return cls(tools, mcp=mcp_client, sessions=sessions, logger=ctx.logger)
88
+
89
+ def __len__(self) -> int:
90
+ return len(self._tools)
91
+
92
+ def __iter__(self) -> Iterator[Tool]:
93
+ return iter(self._tools)
94
+
95
+ def __getitem__(self, index: int) -> Tool:
96
+ return self._tools[index]
97
+
98
+ def find(self, name: str) -> Tool | None:
99
+ return self._by_name.get(name)
100
+
101
+ def local(self) -> list[Tool]:
102
+ """Return only App/global tools executed through Levier."""
103
+ return [tool for tool in self._tools if tool.scope != "mcp"]
104
+
105
+ def mcp(self) -> list[Tool]:
106
+ """Return only tools backed by an MCP server."""
107
+ return [tool for tool in self._tools if tool.scope == "mcp"]
108
+
109
+ def specs(self) -> list[Any]:
110
+ """Return model-facing tool specs for ``ctx.chat``."""
111
+ from .llm.base import ToolSpec as LLMToolSpec
112
+
113
+ return [
114
+ LLMToolSpec(
115
+ name=tool.name,
116
+ description=tool.description,
117
+ input_schema_json=tool.schema_json,
118
+ )
119
+ for tool in self._tools
120
+ ]
121
+
122
+ async def call(
123
+ self,
124
+ name: str,
125
+ arguments: Mapping[str, Any] | str | None = None,
126
+ ) -> ToolResult:
127
+ """Dispatch one tool by its model-facing name."""
128
+ value = self._by_name.get(name)
129
+ if value is None:
130
+ return ToolResult(
131
+ ok=False,
132
+ error_code="TOOL_NOT_FOUND",
133
+ error_message=f"unknown tool {name!r}",
134
+ )
135
+ return await value.call(arguments)
136
+
137
+ async def close(self) -> None:
138
+ """Close every MCP session opened by this toolbox."""
139
+ if self._mcp is None:
140
+ return
141
+ for session_id in self._sessions:
142
+ try:
143
+ await self._mcp.close_session(session_id)
144
+ except Exception as exc: # closing must not mask the run result
145
+ if self._logger is not None:
146
+ self._logger.warning("close MCP session failed: %s", exc)
147
+ self._sessions.clear()
148
+ await self._mcp.close()
149
+ self._mcp = None
150
+
151
+
152
+ def _local_tool(ctx: Any, spec: ToolSpec) -> Tool:
153
+ async def call(payload: str) -> ToolResult:
154
+ return await ctx.call_tool(spec.name, payload)
155
+
156
+ return Tool(
157
+ name=spec.name,
158
+ description=spec.description,
159
+ schema_json=spec.input_schema_json or "{}",
160
+ scope=spec.scope,
161
+ _caller=call,
162
+ )
163
+
164
+
165
+ async def _open_mcp(
166
+ ctx: Any,
167
+ client: McpRuntimeClient,
168
+ binding: McpBinding,
169
+ ) -> tuple[str, list[Tool]]:
170
+ try:
171
+ session = await client.open(binding)
172
+ except McpRuntimeError as exc:
173
+ await ctx.error(exc.code, str(exc), retryable=exc.retryable)
174
+ return "", []
175
+ except Exception as exc: # runtime boundary
176
+ await ctx.error("MCP_RUNTIME_ERROR", str(exc), retryable=True)
177
+ return "", []
178
+ if not session.session_id:
179
+ await ctx.error(
180
+ "MCP_RUNTIME_ERROR",
181
+ f"MCP server {binding.server_name!r} returned no session",
182
+ retryable=True,
183
+ )
184
+ return "", []
185
+
186
+ tools: list[Tool] = []
187
+ for spec in session.tools:
188
+
189
+ async def call(payload: str, *, _name: str = spec.name, _session: str = session.session_id) -> ToolResult:
190
+ invocation_id = new_ulid()
191
+ started = time.monotonic()
192
+ await ctx._emit_safe(
193
+ "TOOL_CALL_BEGIN",
194
+ {
195
+ "invocation_id": invocation_id,
196
+ "tool_name": _name,
197
+ "arguments_json": payload,
198
+ },
199
+ )
200
+ try:
201
+ result = await client.call(_session, _name, payload, _tool_timeout(ctx))
202
+ except McpRuntimeError as exc:
203
+ result = ToolResult(
204
+ ok=False,
205
+ error_code=exc.code,
206
+ error_message=str(exc),
207
+ retryable=exc.retryable,
208
+ )
209
+ except Exception as exc: # runtime boundary
210
+ result = ToolResult(
211
+ ok=False,
212
+ error_code="MCP_RUNTIME_ERROR",
213
+ error_message=str(exc),
214
+ retryable=True,
215
+ )
216
+ data: dict[str, Any] = {
217
+ "invocation_id": invocation_id,
218
+ "tool_name": _name,
219
+ "ok": result.ok,
220
+ "duration_ms": int((time.monotonic() - started) * 1000),
221
+ }
222
+ if result.ok:
223
+ data["result_json"] = result.result_json
224
+ else:
225
+ data["error_code"] = result.error_code
226
+ data["error_message"] = result.error_message
227
+ data["retryable"] = result.retryable
228
+ await ctx._emit_safe("TOOL_CALL_END", data)
229
+ return result
230
+
231
+ tools.append(
232
+ Tool(
233
+ name=spec.name,
234
+ description=spec.description,
235
+ schema_json=spec.input_schema_json or "{}",
236
+ scope="mcp",
237
+ _caller=call,
238
+ )
239
+ )
240
+ return session.session_id, tools
241
+
242
+
243
+ def _mcp_socket() -> str:
244
+ import os
245
+
246
+ value = os.environ.get("LEVIER_MCP_RUNTIME_SOCKET", "").strip()
247
+ if value:
248
+ return value
249
+ from .profile import default_mcp_socket
250
+
251
+ return default_mcp_socket()
252
+
253
+
254
+ def _tool_timeout(ctx: Any) -> int:
255
+ try:
256
+ return int(ctx.timeouts.tool_ms or 60_000)
257
+ except Exception:
258
+ return 60_000
259
+
260
+
261
+ __all__ = ["Tool", "Toolbox"]
@@ -0,0 +1,23 @@
1
+ """Levier - optional tool helpers.
2
+
3
+ Copyright 2026 The Levier Authors.
4
+ """
5
+
6
+ from levier_runtime.tools.base import (
7
+ ExecutorToolProvider,
8
+ ToolExecutor,
9
+ ToolProvider,
10
+ ToolResult,
11
+ UnavailableToolExecutor,
12
+ UnavailableToolProvider,
13
+ as_tool_provider,
14
+ )
15
+ __all__ = [
16
+ "ExecutorToolProvider",
17
+ "ToolExecutor",
18
+ "ToolProvider",
19
+ "ToolResult",
20
+ "UnavailableToolExecutor",
21
+ "UnavailableToolProvider",
22
+ "as_tool_provider",
23
+ ]