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.
- levier_runtime/__init__.py +57 -0
- levier_runtime/channel/__init__.py +5 -0
- levier_runtime/channel/client.py +317 -0
- levier_runtime/channel/envelope.py +57 -0
- levier_runtime/cli.py +116 -0
- levier_runtime/config.py +289 -0
- levier_runtime/context.py +409 -0
- levier_runtime/events.py +100 -0
- levier_runtime/ids.py +36 -0
- levier_runtime/llm/__init__.py +44 -0
- levier_runtime/llm/anthropic.py +410 -0
- levier_runtime/llm/base.py +134 -0
- levier_runtime/llm/http.py +133 -0
- levier_runtime/llm/openai.py +379 -0
- levier_runtime/llm/router.py +56 -0
- levier_runtime/manager.py +272 -0
- levier_runtime/mcp/__init__.py +8 -0
- levier_runtime/mcp/client.py +289 -0
- levier_runtime/profile.py +91 -0
- levier_runtime/react/__init__.py +11 -0
- levier_runtime/react/agent.py +527 -0
- levier_runtime/react/checkpoint.py +193 -0
- levier_runtime/runtime.py +139 -0
- levier_runtime/toolbox.py +261 -0
- levier_runtime/tools/__init__.py +23 -0
- levier_runtime/tools/base.py +131 -0
- levier_runtime/types.py +143 -0
- levier_runtime-0.1.0.dist-info/METADATA +101 -0
- levier_runtime-0.1.0.dist-info/RECORD +37 -0
- levier_runtime-0.1.0.dist-info/WHEEL +5 -0
- levier_runtime-0.1.0.dist-info/top_level.txt +2 -0
- middleware/__init__.py +1 -0
- middleware/runtime/__init__.py +1 -0
- middleware/runtime/v1/__init__.py +1 -0
- middleware/runtime/v1/runtime_pb2.py +98 -0
- middleware/runtime/v1/runtime_pb2.pyi +332 -0
- middleware/runtime/v1/runtime_pb2_grpc.py +84 -0
levier_runtime/config.py
ADDED
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
"""Runtime configuration loading for the Levier Runtime SDK.
|
|
2
|
+
|
|
3
|
+
The public config is intentionally small: middleware connection, one runtime
|
|
4
|
+
identity, capacity, labels, and logging. Optional capabilities are configured
|
|
5
|
+
by the runtime implementation, not by the SDK.
|
|
6
|
+
|
|
7
|
+
Copyright 2026 The Levier Authors.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import os
|
|
13
|
+
from dataclasses import dataclass, field
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any, Mapping
|
|
16
|
+
|
|
17
|
+
import yaml
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class ConfigError(ValueError):
|
|
21
|
+
"""Raised when a runtime configuration file is invalid."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass(frozen=True)
|
|
25
|
+
class MiddlewareConfig:
|
|
26
|
+
"""Levier RuntimeChannel connection settings."""
|
|
27
|
+
|
|
28
|
+
address: str
|
|
29
|
+
auth_token: str = field(default="", repr=False)
|
|
30
|
+
auth_token_file: str = ""
|
|
31
|
+
tls: bool = False
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class RuntimeConfig:
|
|
36
|
+
"""Identity and capacity for one runtime process."""
|
|
37
|
+
|
|
38
|
+
runtime_name: str
|
|
39
|
+
instance_id: str
|
|
40
|
+
middleware: MiddlewareConfig
|
|
41
|
+
runtime_type: str = "normal"
|
|
42
|
+
max_concurrent_runs: int = 4
|
|
43
|
+
labels: Mapping[str, str] = field(default_factory=dict)
|
|
44
|
+
log_level: str = "info"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def load_runtime_config(
|
|
48
|
+
path: str | os.PathLike[str] | None = None,
|
|
49
|
+
*,
|
|
50
|
+
environ: Mapping[str, str] | None = None,
|
|
51
|
+
) -> RuntimeConfig:
|
|
52
|
+
"""Load `runtime.yaml`, then apply `LEVIER_RUNTIME_*` overrides.
|
|
53
|
+
|
|
54
|
+
A runtime can start with no YAML at all. In that case the SDK derives the
|
|
55
|
+
server address, runtime name, and local runtime credential from the user
|
|
56
|
+
profile written by ``levier up``/``levier init``.
|
|
57
|
+
"""
|
|
58
|
+
env = os.environ if environ is None else environ
|
|
59
|
+
from .profile import default_runtime_config
|
|
60
|
+
|
|
61
|
+
configured = path or env.get("LEVIER_RUNTIME_CONFIG", "") or default_runtime_config()
|
|
62
|
+
data: dict[str, Any] = {}
|
|
63
|
+
label = "defaults"
|
|
64
|
+
use_profile_defaults = True
|
|
65
|
+
if configured and str(configured) != ".":
|
|
66
|
+
config_path = Path(configured)
|
|
67
|
+
label = str(config_path)
|
|
68
|
+
try:
|
|
69
|
+
raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
|
|
70
|
+
except OSError as exc:
|
|
71
|
+
raise ConfigError(f"read config {config_path}: {exc}") from exc
|
|
72
|
+
except yaml.YAMLError as exc:
|
|
73
|
+
raise ConfigError(f"parse config {config_path}: {exc}") from exc
|
|
74
|
+
if raw is None:
|
|
75
|
+
raw = {}
|
|
76
|
+
if not isinstance(raw, dict):
|
|
77
|
+
raise ConfigError(f"config {config_path} must be a mapping")
|
|
78
|
+
data = _deep_copy(raw)
|
|
79
|
+
# An empty placeholder file is the no-config case. A non-empty file is
|
|
80
|
+
# explicit and keeps strict field validation.
|
|
81
|
+
use_profile_defaults = not bool(data)
|
|
82
|
+
|
|
83
|
+
_apply_env(data, env)
|
|
84
|
+
if use_profile_defaults:
|
|
85
|
+
_apply_profile_defaults(data, env)
|
|
86
|
+
try:
|
|
87
|
+
return _parse_config(data, env, allow_local_defaults=use_profile_defaults)
|
|
88
|
+
except ConfigError as exc:
|
|
89
|
+
raise ConfigError(f"validate config {label}: {exc}") from exc
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _apply_profile_defaults(data: dict[str, Any], env: Mapping[str, str]) -> None:
|
|
93
|
+
from .profile import (
|
|
94
|
+
default_middleware_address,
|
|
95
|
+
default_runtime_name,
|
|
96
|
+
default_runtime_token,
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
middleware = data.get("middleware")
|
|
100
|
+
if not isinstance(middleware, dict):
|
|
101
|
+
middleware = {}
|
|
102
|
+
data["middleware"] = middleware
|
|
103
|
+
if not middleware.get("address") and not env.get("LEVIER_MIDDLEWARE_ADDRESS"):
|
|
104
|
+
address = default_middleware_address() or "127.0.0.1:9090"
|
|
105
|
+
middleware["address"] = address
|
|
106
|
+
if not middleware.get("auth_token") and not middleware.get("auth_token_file"):
|
|
107
|
+
token = env.get("LEVIER_RUNTIME_TOKEN") or default_runtime_token()
|
|
108
|
+
if token:
|
|
109
|
+
middleware["auth_token"] = token
|
|
110
|
+
|
|
111
|
+
runtime = data.get("runtime")
|
|
112
|
+
if not isinstance(runtime, dict):
|
|
113
|
+
runtime = {}
|
|
114
|
+
data["runtime"] = runtime
|
|
115
|
+
if not runtime.get("name"):
|
|
116
|
+
runtime["name"] = env.get("LEVIER_RUNTIME_NAME") or default_runtime_name() or "local"
|
|
117
|
+
if not runtime.get("instance_id"):
|
|
118
|
+
import socket
|
|
119
|
+
|
|
120
|
+
runtime["instance_id"] = f"{runtime['name']}-{socket.gethostname()}-{os.getpid()}"
|
|
121
|
+
if not runtime.get("type"):
|
|
122
|
+
runtime["type"] = "normal"
|
|
123
|
+
if not runtime.get("max_concurrent_runs"):
|
|
124
|
+
runtime["max_concurrent_runs"] = 4
|
|
125
|
+
if not data.get("logging"):
|
|
126
|
+
data["logging"] = {"level": "info"}
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _parse_config(
|
|
130
|
+
data: dict[str, Any],
|
|
131
|
+
env: Mapping[str, str],
|
|
132
|
+
*,
|
|
133
|
+
allow_local_defaults: bool = False,
|
|
134
|
+
) -> RuntimeConfig:
|
|
135
|
+
middleware_data = _section(data, "middleware", required=True)
|
|
136
|
+
runtime_data = _section(data, "runtime", required=True)
|
|
137
|
+
address = _string(middleware_data, "middleware.address", "127.0.0.1:9090")
|
|
138
|
+
auth_token = _string(middleware_data, "middleware.auth_token", "")
|
|
139
|
+
auth_token_file = _string(middleware_data, "middleware.auth_token_file", "")
|
|
140
|
+
if not auth_token and auth_token_file:
|
|
141
|
+
auth_token = _read_secret_file(auth_token_file)
|
|
142
|
+
if not auth_token and allow_local_defaults and _is_local_address(address):
|
|
143
|
+
# The local Compose stack ships with this development credential.
|
|
144
|
+
auth_token = env.get("LEVIER_RUNTIME_TOKEN") or "change-me"
|
|
145
|
+
if not auth_token:
|
|
146
|
+
raise ConfigError(
|
|
147
|
+
"middleware.auth_token or middleware.auth_token_file is required "
|
|
148
|
+
"(or run `levier up`, which records the local runtime credential)"
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
runtime_name = _string(runtime_data, "runtime.name", "", required=True)
|
|
152
|
+
instance_id = _string(runtime_data, "runtime.instance_id", "", required=True)
|
|
153
|
+
runtime_type = _string(runtime_data, "runtime.type", "normal")
|
|
154
|
+
if runtime_type not in {"normal", "sandbox", "longterm"}:
|
|
155
|
+
raise ConfigError("runtime.type must be normal, sandbox, or longterm")
|
|
156
|
+
max_concurrent_runs = _positive_int(runtime_data, "runtime.max_concurrent_runs", 4)
|
|
157
|
+
labels = _string_map(runtime_data, "runtime.labels")
|
|
158
|
+
logging_data = _section(data, "logging", required=False)
|
|
159
|
+
log_level = _string(logging_data, "logging.level", "info")
|
|
160
|
+
|
|
161
|
+
tls = _boolean(middleware_data, "middleware.tls", False)
|
|
162
|
+
middleware = MiddlewareConfig(
|
|
163
|
+
address=address,
|
|
164
|
+
auth_token=auth_token,
|
|
165
|
+
auth_token_file=auth_token_file,
|
|
166
|
+
tls=tls,
|
|
167
|
+
)
|
|
168
|
+
return RuntimeConfig(
|
|
169
|
+
runtime_name=runtime_name,
|
|
170
|
+
instance_id=instance_id,
|
|
171
|
+
middleware=middleware,
|
|
172
|
+
runtime_type=runtime_type,
|
|
173
|
+
max_concurrent_runs=max_concurrent_runs,
|
|
174
|
+
labels=labels,
|
|
175
|
+
log_level=log_level,
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def _apply_env(data: dict[str, Any], env: Mapping[str, str]) -> None:
|
|
180
|
+
_set(data, "middleware", "address", env.get("LEVIER_MIDDLEWARE_ADDRESS"))
|
|
181
|
+
_set(data, "middleware", "tls", env.get("LEVIER_MIDDLEWARE_TLS"))
|
|
182
|
+
_set(data, "middleware", "auth_token", env.get("LEVIER_RUNTIME_TOKEN"))
|
|
183
|
+
_set(data, "middleware", "auth_token_file", env.get("LEVIER_RUNTIME_TOKEN_FILE"))
|
|
184
|
+
_set(data, "runtime", "name", env.get("LEVIER_RUNTIME_NAME"))
|
|
185
|
+
_set(data, "runtime", "instance_id", env.get("LEVIER_RUNTIME_INSTANCE_ID"))
|
|
186
|
+
_set(data, "runtime", "type", env.get("LEVIER_RUNTIME_TYPE"))
|
|
187
|
+
_set(data, "runtime", "max_concurrent_runs", env.get("LEVIER_RUNTIME_MAX_CONCURRENT_RUNS"))
|
|
188
|
+
labels = env.get("LEVIER_RUNTIME_LABELS")
|
|
189
|
+
if labels is not None:
|
|
190
|
+
_section(data, "runtime", required=True)["labels"] = _parse_labels(labels)
|
|
191
|
+
_set(data, "logging", "level", env.get("LEVIER_RUNTIME_LOG_LEVEL"))
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _section(data: dict[str, Any], name: str, *, required: bool) -> dict[str, Any]:
|
|
195
|
+
value = data.get(name)
|
|
196
|
+
if value is None:
|
|
197
|
+
if required:
|
|
198
|
+
raise ConfigError(f"{name} is required")
|
|
199
|
+
return {}
|
|
200
|
+
if not isinstance(value, dict):
|
|
201
|
+
raise ConfigError(f"{name} must be a mapping")
|
|
202
|
+
return value
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def _string(
|
|
206
|
+
section: dict[str, Any],
|
|
207
|
+
name: str,
|
|
208
|
+
default: str,
|
|
209
|
+
*,
|
|
210
|
+
required: bool = False,
|
|
211
|
+
) -> str:
|
|
212
|
+
value = section.get(name.rsplit(".", 1)[-1], default)
|
|
213
|
+
if not isinstance(value, str):
|
|
214
|
+
raise ConfigError(f"{name} must be a string")
|
|
215
|
+
if required and not value:
|
|
216
|
+
raise ConfigError(f"{name} is required")
|
|
217
|
+
return value
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def _positive_int(section: dict[str, Any], name: str, default: int) -> int:
|
|
221
|
+
value = section.get(name.rsplit(".", 1)[-1], default)
|
|
222
|
+
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
|
|
223
|
+
raise ConfigError(f"{name} must be a positive integer")
|
|
224
|
+
return value
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def _boolean(section: dict[str, Any], name: str, default: bool) -> bool:
|
|
228
|
+
value = section.get(name.rsplit(".", 1)[-1], default)
|
|
229
|
+
if isinstance(value, bool):
|
|
230
|
+
return value
|
|
231
|
+
if isinstance(value, str):
|
|
232
|
+
lowered = value.lower()
|
|
233
|
+
if lowered in {"true", "1", "yes"}:
|
|
234
|
+
return True
|
|
235
|
+
if lowered in {"false", "0", "no"}:
|
|
236
|
+
return False
|
|
237
|
+
raise ConfigError(f"{name} must be a boolean")
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def _string_map(section: dict[str, Any], name: str) -> dict[str, str]:
|
|
241
|
+
value = section.get(name.rsplit(".", 1)[-1], {})
|
|
242
|
+
if not isinstance(value, dict):
|
|
243
|
+
raise ConfigError(f"{name} must be a mapping")
|
|
244
|
+
result: dict[str, str] = {}
|
|
245
|
+
for key, item in value.items():
|
|
246
|
+
if not isinstance(key, str) or not isinstance(item, str):
|
|
247
|
+
raise ConfigError(f"{name} keys and values must be strings")
|
|
248
|
+
result[key] = item
|
|
249
|
+
return result
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def _is_local_address(address: str) -> bool:
|
|
253
|
+
host = address.strip()
|
|
254
|
+
if host.startswith("["):
|
|
255
|
+
host = host[1:].split("]", 1)[0]
|
|
256
|
+
elif ":" in host:
|
|
257
|
+
host = host.rsplit(":", 1)[0]
|
|
258
|
+
return host in {"127.0.0.1", "localhost", "::1", "0.0.0.0", ""}
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def _read_secret_file(path: str) -> str:
|
|
262
|
+
try:
|
|
263
|
+
return Path(path).read_text(encoding="utf-8").strip()
|
|
264
|
+
except OSError as exc:
|
|
265
|
+
raise ConfigError(f"read secret file {path}: {exc}") from exc
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def _parse_labels(value: str) -> dict[str, str]:
|
|
269
|
+
labels: dict[str, str] = {}
|
|
270
|
+
for item in value.split(","):
|
|
271
|
+
key, separator, label_value = item.partition("=")
|
|
272
|
+
if not separator or not key.strip():
|
|
273
|
+
raise ConfigError("LEVIER_RUNTIME_LABELS must use key=value,key=value")
|
|
274
|
+
labels[key.strip()] = label_value.strip()
|
|
275
|
+
return labels
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def _set(data: dict[str, Any], section: str, key: str, value: str | None) -> None:
|
|
279
|
+
if value is None:
|
|
280
|
+
return
|
|
281
|
+
_section(data, section, required=True)[key] = value
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _deep_copy(value: Any) -> Any:
|
|
285
|
+
if isinstance(value, dict):
|
|
286
|
+
return {key: _deep_copy(item) for key, item in value.items()}
|
|
287
|
+
if isinstance(value, list):
|
|
288
|
+
return [_deep_copy(item) for item in value]
|
|
289
|
+
return value
|
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
"""The single runtime-author-facing object.
|
|
2
|
+
|
|
3
|
+
`RunContext` deliberately exposes plain values and high-level methods only.
|
|
4
|
+
Transport details, protobuf messages, sequence numbers, and lease handling stay
|
|
5
|
+
inside the Runtime SDK.
|
|
6
|
+
|
|
7
|
+
The common loop is three calls: `await ctx.toolbox()` returns local and MCP
|
|
8
|
+
tools, `await ctx.chat(...)` calls the resolved model, and
|
|
9
|
+
`await ctx.invoke_all(reply, toolbox=tools)` dispatches every tool call.
|
|
10
|
+
|
|
11
|
+
Copyright 2026 The Levier Authors.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import asyncio
|
|
17
|
+
import json
|
|
18
|
+
import logging
|
|
19
|
+
import time
|
|
20
|
+
from datetime import datetime, timezone
|
|
21
|
+
from typing import Any, Mapping
|
|
22
|
+
|
|
23
|
+
from middleware.runtime.v1 import runtime_pb2
|
|
24
|
+
|
|
25
|
+
from .channel.client import ChannelClient
|
|
26
|
+
from .events import EventWriter
|
|
27
|
+
from .ids import new_ulid
|
|
28
|
+
from .types import (
|
|
29
|
+
McpBinding,
|
|
30
|
+
Message,
|
|
31
|
+
ModelConfig,
|
|
32
|
+
Timeouts,
|
|
33
|
+
ToolResult,
|
|
34
|
+
ToolSpec,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class RuntimeUsageError(ValueError):
|
|
39
|
+
"""Raised when a runtime uses a context operation incorrectly."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class RunContext:
|
|
43
|
+
"""State and operations available to one `run(ctx)` invocation."""
|
|
44
|
+
|
|
45
|
+
def __init__(
|
|
46
|
+
self,
|
|
47
|
+
*,
|
|
48
|
+
runtime_name: str,
|
|
49
|
+
run_id: str,
|
|
50
|
+
app_id: str,
|
|
51
|
+
input_messages: list[Message],
|
|
52
|
+
params: dict[str, Any],
|
|
53
|
+
model: ModelConfig | None,
|
|
54
|
+
tools: list[ToolSpec],
|
|
55
|
+
mcp_bindings: list[McpBinding],
|
|
56
|
+
timeouts: Timeouts,
|
|
57
|
+
session_id: str | None,
|
|
58
|
+
resume_from: bytes | None,
|
|
59
|
+
trace_id: str,
|
|
60
|
+
channel: ChannelClient,
|
|
61
|
+
events: EventWriter,
|
|
62
|
+
attempt: int,
|
|
63
|
+
lease_epoch: int,
|
|
64
|
+
) -> None:
|
|
65
|
+
self.runtime_name = runtime_name
|
|
66
|
+
self.run_id = run_id
|
|
67
|
+
self.app_id = app_id
|
|
68
|
+
self.input = input_messages
|
|
69
|
+
self.params = params
|
|
70
|
+
self.model = model
|
|
71
|
+
self.tools = tools
|
|
72
|
+
self.mcp_bindings = mcp_bindings
|
|
73
|
+
self.timeouts = timeouts
|
|
74
|
+
self.session_id = session_id
|
|
75
|
+
self.resume_from = resume_from
|
|
76
|
+
self.trace_id = trace_id
|
|
77
|
+
self.cancel_event = asyncio.Event()
|
|
78
|
+
self.started_at = datetime.now(tz=timezone.utc)
|
|
79
|
+
self.outcome = ""
|
|
80
|
+
self.task: asyncio.Task[Any] | None = None
|
|
81
|
+
# Useful for runtimes that include attempt information in their own
|
|
82
|
+
# checkpoint or logs; it is not a control-plane action.
|
|
83
|
+
self.attempt = attempt
|
|
84
|
+
|
|
85
|
+
self._channel = channel
|
|
86
|
+
self._events = events
|
|
87
|
+
self._attempt = attempt
|
|
88
|
+
self._lease_epoch = lease_epoch
|
|
89
|
+
self._toolbox = None
|
|
90
|
+
self.logger = logging.LoggerAdapter(
|
|
91
|
+
logging.getLogger("levier_runtime.run"),
|
|
92
|
+
{
|
|
93
|
+
"run_id": run_id,
|
|
94
|
+
"app_id": app_id,
|
|
95
|
+
"runtime_name": runtime_name,
|
|
96
|
+
"attempt": attempt,
|
|
97
|
+
"trace_id": trace_id,
|
|
98
|
+
},
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
@property
|
|
102
|
+
def cancelled(self) -> bool:
|
|
103
|
+
"""Whether the control plane has requested cancellation."""
|
|
104
|
+
return self.cancel_event.is_set()
|
|
105
|
+
|
|
106
|
+
async def reply(self, text: str, *, role: str = "assistant") -> None:
|
|
107
|
+
"""Emit one completed assistant message."""
|
|
108
|
+
await self.emit(
|
|
109
|
+
"MESSAGE_COMPLETED",
|
|
110
|
+
{
|
|
111
|
+
"message_id": new_ulid(),
|
|
112
|
+
"role": role,
|
|
113
|
+
"content": text,
|
|
114
|
+
},
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
async def emit(
|
|
118
|
+
self,
|
|
119
|
+
event_type: str,
|
|
120
|
+
data: dict[str, Any],
|
|
121
|
+
*,
|
|
122
|
+
ephemeral: bool = False,
|
|
123
|
+
) -> None:
|
|
124
|
+
"""Emit one event by protocol name, e.g. MESSAGE_DELTA.
|
|
125
|
+
|
|
126
|
+
The SDK assigns sequence numbers and envelope scope.
|
|
127
|
+
"""
|
|
128
|
+
await self._events.emit(event_type, data, ephemeral=ephemeral)
|
|
129
|
+
|
|
130
|
+
async def toolbox(self) -> "Any":
|
|
131
|
+
"""Return every local and MCP tool as one callable sequence.
|
|
132
|
+
|
|
133
|
+
MCP sessions are opened lazily on the first call and closed when the Run
|
|
134
|
+
ends. Runtime authors do not need to construct an MCP client.
|
|
135
|
+
"""
|
|
136
|
+
if self._toolbox is None:
|
|
137
|
+
from .toolbox import Toolbox
|
|
138
|
+
|
|
139
|
+
self._toolbox = await Toolbox.open(self)
|
|
140
|
+
return self._toolbox
|
|
141
|
+
|
|
142
|
+
async def chat(
|
|
143
|
+
self,
|
|
144
|
+
messages: "list[Any] | None" = None,
|
|
145
|
+
*,
|
|
146
|
+
tools: "Any" = None,
|
|
147
|
+
on_delta: "Any" = None,
|
|
148
|
+
) -> "Any":
|
|
149
|
+
"""Call the model already resolved for this Run.
|
|
150
|
+
|
|
151
|
+
``ctx.chat(ctx.input)`` uses every visible tool. The returned provider
|
|
152
|
+
response has ``content`` and ``tool_calls``. Provider failures become an
|
|
153
|
+
ERROR event and a failed Run automatically.
|
|
154
|
+
"""
|
|
155
|
+
if self.model is None:
|
|
156
|
+
raise RuntimeUsageError("this run has no model; configure a provider and make it the default")
|
|
157
|
+
from .llm.base import Message as LLMMessage
|
|
158
|
+
from .llm.base import ModelConfig as LLMModelConfig
|
|
159
|
+
from .llm.router import ProviderRouter
|
|
160
|
+
|
|
161
|
+
values = list(self.input if messages is None else messages)
|
|
162
|
+
converted = []
|
|
163
|
+
for message in values:
|
|
164
|
+
if isinstance(message, LLMMessage):
|
|
165
|
+
converted.append(message)
|
|
166
|
+
elif isinstance(message, Mapping):
|
|
167
|
+
converted.append(
|
|
168
|
+
LLMMessage(
|
|
169
|
+
role=str(message.get("role", "user")),
|
|
170
|
+
content=str(message.get("content", "")),
|
|
171
|
+
name=str(message.get("name", "")),
|
|
172
|
+
tool_call_id=str(message.get("tool_call_id", "")),
|
|
173
|
+
)
|
|
174
|
+
)
|
|
175
|
+
else:
|
|
176
|
+
converted.append(
|
|
177
|
+
LLMMessage(
|
|
178
|
+
role=str(getattr(message, "role", "user")),
|
|
179
|
+
content=str(getattr(message, "content", "")),
|
|
180
|
+
name=str(getattr(message, "name", "")),
|
|
181
|
+
)
|
|
182
|
+
)
|
|
183
|
+
|
|
184
|
+
if tools is None:
|
|
185
|
+
tools = await self.toolbox()
|
|
186
|
+
specs = _tool_specs(tools)
|
|
187
|
+
model = LLMModelConfig(
|
|
188
|
+
provider=self.model.provider,
|
|
189
|
+
model=self.model.model,
|
|
190
|
+
api_key=self.model.api_key,
|
|
191
|
+
base_url=self.model.base_url,
|
|
192
|
+
params=dict(self.model.params),
|
|
193
|
+
)
|
|
194
|
+
return await ProviderRouter().complete(converted, specs, model, on_delta=on_delta)
|
|
195
|
+
|
|
196
|
+
async def invoke(
|
|
197
|
+
self,
|
|
198
|
+
call: "Any",
|
|
199
|
+
*,
|
|
200
|
+
toolbox: "Any" = None,
|
|
201
|
+
) -> ToolResult:
|
|
202
|
+
"""Parse one model tool call and execute it, local or MCP."""
|
|
203
|
+
name, arguments = _tool_call(call)
|
|
204
|
+
active = toolbox if toolbox is not None else await self.toolbox()
|
|
205
|
+
return await active.call(name, arguments)
|
|
206
|
+
|
|
207
|
+
async def invoke_all(
|
|
208
|
+
self,
|
|
209
|
+
response: "Any",
|
|
210
|
+
*,
|
|
211
|
+
toolbox: "Any" = None,
|
|
212
|
+
) -> "list[ToolResult]":
|
|
213
|
+
"""Execute every tool call in one provider response."""
|
|
214
|
+
calls = getattr(response, "tool_calls", response)
|
|
215
|
+
active = toolbox if toolbox is not None else await self.toolbox()
|
|
216
|
+
results: list[ToolResult] = []
|
|
217
|
+
for call in calls:
|
|
218
|
+
results.append(await self.invoke(call, toolbox=active))
|
|
219
|
+
return results
|
|
220
|
+
|
|
221
|
+
async def call_tool(
|
|
222
|
+
self,
|
|
223
|
+
name: str,
|
|
224
|
+
arguments: Mapping[str, Any] | str | None = None,
|
|
225
|
+
*,
|
|
226
|
+
timeout_ms: int | None = None,
|
|
227
|
+
emit_events: bool = True,
|
|
228
|
+
) -> ToolResult:
|
|
229
|
+
"""Call one tool through the middleware tool bridge.
|
|
230
|
+
|
|
231
|
+
By default the SDK emits TOOL_CALL_BEGIN/END and owns tool-call
|
|
232
|
+
observability. Runtimes that already emit those events can pass
|
|
233
|
+
``emit_events=False`` to avoid duplicates.
|
|
234
|
+
"""
|
|
235
|
+
if not name:
|
|
236
|
+
raise RuntimeUsageError("tool name is required")
|
|
237
|
+
if isinstance(arguments, Mapping):
|
|
238
|
+
arguments_json = json.dumps(
|
|
239
|
+
arguments,
|
|
240
|
+
ensure_ascii=False,
|
|
241
|
+
separators=(",", ":"),
|
|
242
|
+
)
|
|
243
|
+
elif arguments is None:
|
|
244
|
+
arguments_json = "{}"
|
|
245
|
+
elif isinstance(arguments, str):
|
|
246
|
+
arguments_json = arguments
|
|
247
|
+
else:
|
|
248
|
+
raise RuntimeUsageError("tool arguments must be a mapping or JSON string")
|
|
249
|
+
|
|
250
|
+
invocation_id = new_ulid()
|
|
251
|
+
if emit_events:
|
|
252
|
+
await self._emit_safe(
|
|
253
|
+
"TOOL_CALL_BEGIN",
|
|
254
|
+
{
|
|
255
|
+
"invocation_id": invocation_id,
|
|
256
|
+
"tool_name": name,
|
|
257
|
+
"arguments_json": arguments_json,
|
|
258
|
+
},
|
|
259
|
+
)
|
|
260
|
+
|
|
261
|
+
started = time.monotonic()
|
|
262
|
+
timeout = timeout_ms or self.timeouts.tool_ms or 60_000
|
|
263
|
+
try:
|
|
264
|
+
response = await self._channel.request(
|
|
265
|
+
runtime_pb2.ToolCallRequest(
|
|
266
|
+
invocation_id=invocation_id,
|
|
267
|
+
tool_name=name,
|
|
268
|
+
arguments_json=arguments_json,
|
|
269
|
+
timeout_ms=timeout,
|
|
270
|
+
),
|
|
271
|
+
"tool_call_request",
|
|
272
|
+
run_id=self.run_id,
|
|
273
|
+
attempt=self._attempt,
|
|
274
|
+
lease_epoch=self._lease_epoch,
|
|
275
|
+
timeout=max(timeout / 1000.0 + 1.0, 1.0),
|
|
276
|
+
)
|
|
277
|
+
result = ToolResult.from_proto(response.tool_call_result)
|
|
278
|
+
except Exception as exc:
|
|
279
|
+
result = ToolResult(
|
|
280
|
+
ok=False,
|
|
281
|
+
error_code="TOOL_TRANSPORT_ERROR",
|
|
282
|
+
error_message=str(exc),
|
|
283
|
+
retryable=True,
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
if emit_events:
|
|
287
|
+
data: dict[str, Any] = {
|
|
288
|
+
"invocation_id": invocation_id,
|
|
289
|
+
"tool_name": name,
|
|
290
|
+
"ok": result.ok,
|
|
291
|
+
"duration_ms": int((time.monotonic() - started) * 1000),
|
|
292
|
+
}
|
|
293
|
+
if result.ok:
|
|
294
|
+
data["result_json"] = result.result_json
|
|
295
|
+
else:
|
|
296
|
+
data["error_code"] = result.error_code
|
|
297
|
+
data["error_message"] = result.error_message
|
|
298
|
+
data["retryable"] = result.retryable
|
|
299
|
+
await self._emit_safe("TOOL_CALL_END", data)
|
|
300
|
+
return result
|
|
301
|
+
|
|
302
|
+
async def error(
|
|
303
|
+
self,
|
|
304
|
+
code: str,
|
|
305
|
+
message: str,
|
|
306
|
+
*,
|
|
307
|
+
retryable: bool = False,
|
|
308
|
+
data: dict[str, Any] | None = None,
|
|
309
|
+
) -> None:
|
|
310
|
+
"""Emit one normalized ERROR event."""
|
|
311
|
+
payload: dict[str, Any] = {
|
|
312
|
+
"code": code,
|
|
313
|
+
"message": message,
|
|
314
|
+
"retryable": retryable,
|
|
315
|
+
}
|
|
316
|
+
if data:
|
|
317
|
+
payload.update(data)
|
|
318
|
+
await self.emit("ERROR", payload)
|
|
319
|
+
|
|
320
|
+
async def _emit_safe(self, event_type: str, data: dict[str, Any]) -> None:
|
|
321
|
+
"""Emit an SDK observability event without failing the run itself."""
|
|
322
|
+
try:
|
|
323
|
+
await self.emit(event_type, data)
|
|
324
|
+
except Exception as exc: # noqa: BLE001 - observability must not mask run
|
|
325
|
+
self.logger.warning("runtime event emission failed", extra={
|
|
326
|
+
"event_type": event_type,
|
|
327
|
+
"error": str(exc),
|
|
328
|
+
})
|
|
329
|
+
|
|
330
|
+
async def checkpoint(self, state: bytes | Mapping[str, Any]) -> None:
|
|
331
|
+
"""Send an opaque checkpoint for this session.
|
|
332
|
+
|
|
333
|
+
The SDK transports the bytes; the runtime owns their schema.
|
|
334
|
+
"""
|
|
335
|
+
if not self.session_id:
|
|
336
|
+
raise RuntimeUsageError("checkpoint requires session_id")
|
|
337
|
+
if isinstance(state, Mapping):
|
|
338
|
+
data = json.dumps(
|
|
339
|
+
state,
|
|
340
|
+
ensure_ascii=False,
|
|
341
|
+
separators=(",", ":"),
|
|
342
|
+
).encode("utf-8")
|
|
343
|
+
elif isinstance(state, (bytes, bytearray)):
|
|
344
|
+
data = bytes(state)
|
|
345
|
+
else:
|
|
346
|
+
raise RuntimeUsageError("checkpoint state must be bytes or a mapping")
|
|
347
|
+
|
|
348
|
+
watermark = await self._events.emit_checkpoint(
|
|
349
|
+
self.session_id,
|
|
350
|
+
data,
|
|
351
|
+
watermark=self._events.seq,
|
|
352
|
+
)
|
|
353
|
+
await self.emit(
|
|
354
|
+
"CHECKPOINT_SAVED",
|
|
355
|
+
{
|
|
356
|
+
"session_id": self.session_id,
|
|
357
|
+
"event_seq_watermark": watermark,
|
|
358
|
+
},
|
|
359
|
+
)
|
|
360
|
+
|
|
361
|
+
async def close_toolbox(self) -> None:
|
|
362
|
+
"""Close any MCP sessions opened by :meth:`toolbox`."""
|
|
363
|
+
if self._toolbox is None:
|
|
364
|
+
return
|
|
365
|
+
await self._toolbox.close()
|
|
366
|
+
self._toolbox = None
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def _tool_specs(tools: Any) -> list[Any]:
|
|
370
|
+
from .llm.base import ToolSpec as LLMToolSpec
|
|
371
|
+
|
|
372
|
+
if hasattr(tools, "specs") and callable(tools.specs):
|
|
373
|
+
return list(tools.specs())
|
|
374
|
+
result = []
|
|
375
|
+
for tool in tools:
|
|
376
|
+
if isinstance(tool, LLMToolSpec):
|
|
377
|
+
result.append(tool)
|
|
378
|
+
continue
|
|
379
|
+
schema = getattr(tool, "schema_json", "") or getattr(tool, "input_schema_json", "")
|
|
380
|
+
if not schema:
|
|
381
|
+
schema_value = getattr(tool, "schema", None)
|
|
382
|
+
if isinstance(schema_value, Mapping):
|
|
383
|
+
schema = json.dumps(schema_value, ensure_ascii=False, separators=(",", ":"))
|
|
384
|
+
result.append(
|
|
385
|
+
LLMToolSpec(
|
|
386
|
+
name=str(getattr(tool, "name", "")),
|
|
387
|
+
description=str(getattr(tool, "description", "")),
|
|
388
|
+
input_schema_json=str(schema or "{}"),
|
|
389
|
+
)
|
|
390
|
+
)
|
|
391
|
+
return result
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def _tool_call(call: Any) -> tuple[str, str]:
|
|
395
|
+
if isinstance(call, Mapping):
|
|
396
|
+
name = str(call.get("name", ""))
|
|
397
|
+
arguments = call.get("arguments_json", call.get("arguments", "{}"))
|
|
398
|
+
else:
|
|
399
|
+
name = str(getattr(call, "name", ""))
|
|
400
|
+
arguments = getattr(call, "arguments_json", None)
|
|
401
|
+
if arguments is None:
|
|
402
|
+
arguments = getattr(call, "arguments", "{}")
|
|
403
|
+
if not name:
|
|
404
|
+
raise RuntimeUsageError("tool call has no name")
|
|
405
|
+
if isinstance(arguments, Mapping):
|
|
406
|
+
return name, json.dumps(arguments, ensure_ascii=False, separators=(",", ":"))
|
|
407
|
+
if arguments is None:
|
|
408
|
+
return name, "{}"
|
|
409
|
+
return name, str(arguments)
|