airalogy-engine 0.0.1__tar.gz

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.

Potentially problematic release.


This version of airalogy-engine might be problematic. Click here for more details.

@@ -0,0 +1,158 @@
1
+ Metadata-Version: 2.3
2
+ Name: airalogy-engine
3
+ Version: 0.0.1
4
+ Summary: Airalogy protocol execute sandbox
5
+ Author: Airalogy Team
6
+ License: Apache-2.0
7
+ Classifier: Development Status :: 4 - Beta
8
+ Classifier: Programming Language :: Python
9
+ Classifier: Programming Language :: Python :: 3.13
10
+ Classifier: Programming Language :: Python :: Implementation :: CPython
11
+ Requires-Dist: boxlite==0.8.2
12
+ Requires-Python: >=3.13
13
+ Project-URL: Documentation, https://github.com/airalogy/airalogy-engine#readme
14
+ Project-URL: Source, https://github.com/airalogy/airalogy-engine
15
+ Description-Content-Type: text/markdown
16
+
17
+ # airalogy-engine (Python)
18
+
19
+ Airalogy protocol execution sandbox for Python. Run protocol packages (`parse`, `assign`, `validate`) inside a secure [BoxLite](https://github.com/boxlite-ai/boxlite) sandbox.
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ pip install airalogy-engine
25
+ ```
26
+
27
+ ## Sandbox Image
28
+
29
+ The engine runs protocol code in a BoxLite sandbox. You can use either a **remote Docker image** or a **local OCI rootfs directory**.
30
+
31
+ ### Remote Image
32
+
33
+ ```python
34
+ from airalogy_engine import AiralogyEngine
35
+
36
+ engine = AiralogyEngine(image="numbcoder/airalogy-engine:0.1")
37
+ result = await engine.parse_protocol(protocol_path)
38
+ ```
39
+
40
+ ### Local OCI Rootfs (Recommended)
41
+
42
+ Build and export the image locally for faster, offline execution:
43
+
44
+ ```bash
45
+ docker build -t airalogy-engine:latest .
46
+ docker save airalogy-engine:latest -o airalogy-engine-image.tar
47
+ mkdir airalogy-engine-image
48
+ tar -xf airalogy-engine-image.tar -C airalogy-engine-image
49
+ ```
50
+
51
+ Then use `rootfs_path`:
52
+
53
+ ```python
54
+ from airalogy_engine import AiralogyEngine
55
+
56
+ engine = AiralogyEngine(rootfs_path="./airalogy-engine-image")
57
+ result = await engine.parse_protocol(protocol_path)
58
+ ```
59
+
60
+ > If neither `image` nor `rootfs_path` is provided, the engine falls back to the default remote image `numbcoder/airalogy-engine:0.1`.
61
+
62
+ ## Usage
63
+
64
+ ```python
65
+ import asyncio
66
+ from airalogy_engine import AiralogyEngine
67
+
68
+ async def main():
69
+ protocol_path = "/path/to/your/protocol"
70
+ rootfs_path = "/path/to/airalogy-engine-image" # or use image="..." instead
71
+ engine = AiralogyEngine(
72
+ rootfs_path=rootfs_path,
73
+ boxlite_home="/tmp/airalogy-engine-worker-1",
74
+ )
75
+
76
+ # 1. Parse the protocol
77
+ result = await engine.parse_protocol(protocol_path, env_vars={"API_KEY": "xxx"})
78
+ print(result["data"]["meta_data"])
79
+ print(result["data"]["json_schema"])
80
+
81
+ # 2. Assign a variable
82
+ result = await engine.assign_variable(
83
+ protocol_path,
84
+ var_name="duration",
85
+ dependent_data={"seconds": 3600},
86
+ env_vars={"API_KEY": "xxx"},
87
+ )
88
+ print(result["data"])
89
+
90
+ # 3. Validate variables
91
+ result = await engine.validate_variables(
92
+ protocol_path,
93
+ variables={"seconds": 60, "duration": "PT1M"},
94
+ )
95
+ print(result["data"])
96
+
97
+ await engine.close()
98
+
99
+ asyncio.run(main())
100
+ ```
101
+
102
+ You can also use the engine as an async context manager:
103
+
104
+ ```python
105
+ async with AiralogyEngine(rootfs_path=rootfs_path, boxlite_home="/tmp/worker-1") as engine:
106
+ result = await engine.parse_protocol(protocol_path)
107
+ ```
108
+
109
+ ## API
110
+
111
+ | API | Description |
112
+ |---|---|
113
+ | `AiralogyEngine(boxlite_home=None, image=None, rootfs_path=None, timeout=300, memory_mib=512, cpus=1)` | Create an engine bound to one BoxLite runtime home and sandbox configuration |
114
+ | `engine.parse_protocol(protocol_path, env_vars=None, timeout=None, debug=False, log_file="protocol_debug.log")` | Parse a protocol and return schema, metadata, fields |
115
+ | `engine.assign_variable(protocol_path, var_name, dependent_data, env_vars=None, timeout=None, debug=False, log_file="protocol_debug.log")` | Assign a variable using assigner functions |
116
+ | `engine.validate_variables(protocol_path, variables, env_vars=None, timeout=None, debug=False, log_file="protocol_debug.log")` | Validate variable values against the protocol model |
117
+ | `await engine.close()` | Release this engine's BoxLite runtime reference |
118
+
119
+ All engine methods are `async` and return a `dict` with `success`, `message`, and `data` keys.
120
+
121
+ **Engine parameters**:
122
+ - `boxlite_home`: BoxLite runtime home directory. Use a distinct value for each OS process when running multiple workers.
123
+ - `image`: Remote Docker image name (e.g., `"numbcoder/airalogy-engine:0.1"`).
124
+ - `rootfs_path`: Path to a local OCI rootfs directory (overrides `image`).
125
+ - `timeout`: Execution timeout in seconds (default: 300). The sandboxed process will be killed once it times out.
126
+ - `memory_mib`: Memory limit in MiB (default: 512).
127
+ - `cpus`: CPU limit (default: 1).
128
+
129
+ ## Concurrency
130
+
131
+ Use one `AiralogyEngine` instance per worker process and run concurrent operations through that object:
132
+
133
+ ```python
134
+ engine = AiralogyEngine(rootfs_path=rootfs_path, boxlite_home="/tmp/worker-1")
135
+
136
+ results = await asyncio.gather(
137
+ engine.parse_protocol(protocol_a),
138
+ engine.parse_protocol(protocol_b),
139
+ )
140
+ ```
141
+
142
+ BoxLite locks each runtime home per OS process. Two independent processes must not share the same `boxlite_home` or default `~/.boxlite`; give each process a distinct directory, for example `/tmp/airalogy-worker-1` and `/tmp/airalogy-worker-2`.
143
+
144
+ ## Testing
145
+
146
+ ```bash
147
+ cd python
148
+ uv sync
149
+
150
+ # Default: local OCI rootfs mode
151
+ uv run pytest tests/ -v
152
+
153
+ # Custom rootfs path
154
+ uv run pytest tests/ -v --sandbox-mode=rootfs --rootfs-path=../airalogy-engine-0.1
155
+
156
+ # Remote image mode
157
+ uv run pytest tests/ -v --sandbox-mode=image --sandbox-image=numbcoder/airalogy-engine:0.1
158
+ ```
@@ -0,0 +1,142 @@
1
+ # airalogy-engine (Python)
2
+
3
+ Airalogy protocol execution sandbox for Python. Run protocol packages (`parse`, `assign`, `validate`) inside a secure [BoxLite](https://github.com/boxlite-ai/boxlite) sandbox.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install airalogy-engine
9
+ ```
10
+
11
+ ## Sandbox Image
12
+
13
+ The engine runs protocol code in a BoxLite sandbox. You can use either a **remote Docker image** or a **local OCI rootfs directory**.
14
+
15
+ ### Remote Image
16
+
17
+ ```python
18
+ from airalogy_engine import AiralogyEngine
19
+
20
+ engine = AiralogyEngine(image="numbcoder/airalogy-engine:0.1")
21
+ result = await engine.parse_protocol(protocol_path)
22
+ ```
23
+
24
+ ### Local OCI Rootfs (Recommended)
25
+
26
+ Build and export the image locally for faster, offline execution:
27
+
28
+ ```bash
29
+ docker build -t airalogy-engine:latest .
30
+ docker save airalogy-engine:latest -o airalogy-engine-image.tar
31
+ mkdir airalogy-engine-image
32
+ tar -xf airalogy-engine-image.tar -C airalogy-engine-image
33
+ ```
34
+
35
+ Then use `rootfs_path`:
36
+
37
+ ```python
38
+ from airalogy_engine import AiralogyEngine
39
+
40
+ engine = AiralogyEngine(rootfs_path="./airalogy-engine-image")
41
+ result = await engine.parse_protocol(protocol_path)
42
+ ```
43
+
44
+ > If neither `image` nor `rootfs_path` is provided, the engine falls back to the default remote image `numbcoder/airalogy-engine:0.1`.
45
+
46
+ ## Usage
47
+
48
+ ```python
49
+ import asyncio
50
+ from airalogy_engine import AiralogyEngine
51
+
52
+ async def main():
53
+ protocol_path = "/path/to/your/protocol"
54
+ rootfs_path = "/path/to/airalogy-engine-image" # or use image="..." instead
55
+ engine = AiralogyEngine(
56
+ rootfs_path=rootfs_path,
57
+ boxlite_home="/tmp/airalogy-engine-worker-1",
58
+ )
59
+
60
+ # 1. Parse the protocol
61
+ result = await engine.parse_protocol(protocol_path, env_vars={"API_KEY": "xxx"})
62
+ print(result["data"]["meta_data"])
63
+ print(result["data"]["json_schema"])
64
+
65
+ # 2. Assign a variable
66
+ result = await engine.assign_variable(
67
+ protocol_path,
68
+ var_name="duration",
69
+ dependent_data={"seconds": 3600},
70
+ env_vars={"API_KEY": "xxx"},
71
+ )
72
+ print(result["data"])
73
+
74
+ # 3. Validate variables
75
+ result = await engine.validate_variables(
76
+ protocol_path,
77
+ variables={"seconds": 60, "duration": "PT1M"},
78
+ )
79
+ print(result["data"])
80
+
81
+ await engine.close()
82
+
83
+ asyncio.run(main())
84
+ ```
85
+
86
+ You can also use the engine as an async context manager:
87
+
88
+ ```python
89
+ async with AiralogyEngine(rootfs_path=rootfs_path, boxlite_home="/tmp/worker-1") as engine:
90
+ result = await engine.parse_protocol(protocol_path)
91
+ ```
92
+
93
+ ## API
94
+
95
+ | API | Description |
96
+ |---|---|
97
+ | `AiralogyEngine(boxlite_home=None, image=None, rootfs_path=None, timeout=300, memory_mib=512, cpus=1)` | Create an engine bound to one BoxLite runtime home and sandbox configuration |
98
+ | `engine.parse_protocol(protocol_path, env_vars=None, timeout=None, debug=False, log_file="protocol_debug.log")` | Parse a protocol and return schema, metadata, fields |
99
+ | `engine.assign_variable(protocol_path, var_name, dependent_data, env_vars=None, timeout=None, debug=False, log_file="protocol_debug.log")` | Assign a variable using assigner functions |
100
+ | `engine.validate_variables(protocol_path, variables, env_vars=None, timeout=None, debug=False, log_file="protocol_debug.log")` | Validate variable values against the protocol model |
101
+ | `await engine.close()` | Release this engine's BoxLite runtime reference |
102
+
103
+ All engine methods are `async` and return a `dict` with `success`, `message`, and `data` keys.
104
+
105
+ **Engine parameters**:
106
+ - `boxlite_home`: BoxLite runtime home directory. Use a distinct value for each OS process when running multiple workers.
107
+ - `image`: Remote Docker image name (e.g., `"numbcoder/airalogy-engine:0.1"`).
108
+ - `rootfs_path`: Path to a local OCI rootfs directory (overrides `image`).
109
+ - `timeout`: Execution timeout in seconds (default: 300). The sandboxed process will be killed once it times out.
110
+ - `memory_mib`: Memory limit in MiB (default: 512).
111
+ - `cpus`: CPU limit (default: 1).
112
+
113
+ ## Concurrency
114
+
115
+ Use one `AiralogyEngine` instance per worker process and run concurrent operations through that object:
116
+
117
+ ```python
118
+ engine = AiralogyEngine(rootfs_path=rootfs_path, boxlite_home="/tmp/worker-1")
119
+
120
+ results = await asyncio.gather(
121
+ engine.parse_protocol(protocol_a),
122
+ engine.parse_protocol(protocol_b),
123
+ )
124
+ ```
125
+
126
+ BoxLite locks each runtime home per OS process. Two independent processes must not share the same `boxlite_home` or default `~/.boxlite`; give each process a distinct directory, for example `/tmp/airalogy-worker-1` and `/tmp/airalogy-worker-2`.
127
+
128
+ ## Testing
129
+
130
+ ```bash
131
+ cd python
132
+ uv sync
133
+
134
+ # Default: local OCI rootfs mode
135
+ uv run pytest tests/ -v
136
+
137
+ # Custom rootfs path
138
+ uv run pytest tests/ -v --sandbox-mode=rootfs --rootfs-path=../airalogy-engine-0.1
139
+
140
+ # Remote image mode
141
+ uv run pytest tests/ -v --sandbox-mode=image --sandbox-image=numbcoder/airalogy-engine:0.1
142
+ ```
@@ -0,0 +1,30 @@
1
+ [project]
2
+ name = "airalogy-engine"
3
+ version = "0.0.1"
4
+ description = "Airalogy protocol execute sandbox"
5
+ readme = "README.md"
6
+ authors = [{ name = "Airalogy Team" }]
7
+ requires-python = ">=3.13"
8
+ dependencies = ["boxlite==0.8.2"]
9
+ classifiers = [
10
+ "Development Status :: 4 - Beta",
11
+ "Programming Language :: Python",
12
+ "Programming Language :: Python :: 3.13",
13
+ "Programming Language :: Python :: Implementation :: CPython",
14
+ ]
15
+ license = { text = "Apache-2.0" }
16
+
17
+ [project.urls]
18
+ Documentation = "https://github.com/airalogy/airalogy-engine#readme"
19
+ Source = "https://github.com/airalogy/airalogy-engine"
20
+
21
+
22
+ [build-system]
23
+ requires = ["uv_build>=0.11,<0.12"]
24
+ build-backend = "uv_build"
25
+
26
+ [tool.uv]
27
+ required-version = ">=0.11,<0.12"
28
+
29
+ [dependency-groups]
30
+ dev = ["airalogy~=0.5.0", "pytest>=9.0.2", "pytest-asyncio>=0.25.0"]
@@ -0,0 +1,9 @@
1
+ """Airalogy Engine - Protocol execution sandbox.
2
+
3
+ Provides ``AiralogyEngine`` for running protocol packages inside a secure
4
+ BoxLite sandbox.
5
+ """
6
+
7
+ from airalogy_engine.engine import AiralogyEngine
8
+
9
+ __all__ = ["AiralogyEngine"]
@@ -0,0 +1,481 @@
1
+ import asyncio
2
+ import atexit
3
+ import json
4
+ import os
5
+ import tempfile
6
+ import threading
7
+ from contextlib import suppress
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from boxlite import Box, Boxlite, BoxOptions, CopyOptions, Options
12
+ from boxlite.errors import BoxliteError
13
+
14
+ # Locate protocol_executor.py relative to this file
15
+ _EXECUTOR_PATH = str(Path(__file__).parent / "protocol_executor.py")
16
+ _WORKING_DIR = "/home/airalogy/protocols"
17
+ _SANDBOX_LOG_FILE = "protocol_debug.log"
18
+ DEFAULT_IMAGE = "numbcoder/airalogy-engine:0.1"
19
+ _COPY_OPTIONS = CopyOptions(
20
+ recursive=True,
21
+ overwrite=True,
22
+ follow_symlinks=False,
23
+ include_parent=False,
24
+ )
25
+ _BACKGROUND_CLEANUP_TASKS: set[asyncio.Task[Any]] = set()
26
+ _RUNTIME_REGISTRY_LOCK = threading.Lock()
27
+ _RUNTIME_REGISTRY: dict[str, "_RuntimeEntry"] = {}
28
+
29
+
30
+ class _RuntimeEntry:
31
+ def __init__(self, runtime: Boxlite) -> None:
32
+ self.runtime = runtime
33
+ self.ref_count = 0
34
+
35
+
36
+ def _resolve_boxlite_home(boxlite_home: str | None) -> str:
37
+ if boxlite_home is not None:
38
+ return str(Path(boxlite_home).expanduser().resolve())
39
+
40
+ configured_home = os.environ.get("BOXLITE_HOME")
41
+ if configured_home:
42
+ return str(Path(configured_home).expanduser().resolve())
43
+
44
+ return str(Path.home().joinpath(".boxlite").resolve())
45
+
46
+
47
+ def _acquire_runtime(boxlite_home: str | None) -> tuple[str, Boxlite]:
48
+ key = _resolve_boxlite_home(boxlite_home)
49
+
50
+ with _RUNTIME_REGISTRY_LOCK:
51
+ entry = _RUNTIME_REGISTRY.get(key)
52
+ if entry is None:
53
+ runtime = (
54
+ Boxlite.default()
55
+ if boxlite_home is None
56
+ else Boxlite(Options(home_dir=key))
57
+ )
58
+ entry = _RuntimeEntry(runtime)
59
+ _RUNTIME_REGISTRY[key] = entry
60
+
61
+ entry.ref_count += 1
62
+ return key, entry.runtime
63
+
64
+
65
+ def _release_runtime(key: str) -> None:
66
+ runtime: Boxlite | None = None
67
+
68
+ with _RUNTIME_REGISTRY_LOCK:
69
+ entry = _RUNTIME_REGISTRY.get(key)
70
+ if entry is None:
71
+ return
72
+
73
+ entry.ref_count -= 1
74
+ if entry.ref_count <= 0:
75
+ runtime = entry.runtime
76
+ del _RUNTIME_REGISTRY[key]
77
+
78
+ if runtime is not None:
79
+ with suppress(Exception):
80
+ runtime.close()
81
+
82
+
83
+ def _close_all_runtimes() -> None:
84
+ with _RUNTIME_REGISTRY_LOCK:
85
+ runtimes = [entry.runtime for entry in _RUNTIME_REGISTRY.values()]
86
+ _RUNTIME_REGISTRY.clear()
87
+
88
+ for runtime in runtimes:
89
+ with suppress(Exception):
90
+ runtime.close()
91
+
92
+
93
+ def _is_pyo3_panic(exc: BaseException) -> bool:
94
+ exc_type = type(exc)
95
+ return (
96
+ exc_type.__module__ == "pyo3_runtime" and exc_type.__name__ == "PanicException"
97
+ )
98
+
99
+
100
+ atexit.register(_close_all_runtimes)
101
+
102
+
103
+ async def _copy_out_log(box: Box, log_file: str) -> None:
104
+ """Copy the executor log from sandbox and append to the host log file."""
105
+ tmp_dir = tempfile.mkdtemp()
106
+ try:
107
+ await box.copy_out(
108
+ f"{_WORKING_DIR}/{_SANDBOX_LOG_FILE}",
109
+ tmp_dir,
110
+ _COPY_OPTIONS,
111
+ )
112
+ tmp_log = Path(tmp_dir) / _SANDBOX_LOG_FILE
113
+ if tmp_log.exists():
114
+ log_content = tmp_log.read_text(encoding="utf-8")
115
+ if log_content:
116
+ with open(log_file, "a", encoding="utf-8") as f:
117
+ f.write(log_content)
118
+ except Exception:
119
+ pass
120
+ finally:
121
+ import shutil
122
+
123
+ shutil.rmtree(tmp_dir, ignore_errors=True)
124
+
125
+
126
+ def _decode_stream_line(line: str | bytes) -> str:
127
+ if isinstance(line, bytes):
128
+ return line.decode("utf-8", errors="replace")
129
+ return line
130
+
131
+
132
+ async def _collect_output_stream(stream: Any, output_lines: list[str]) -> None:
133
+ """Consume a BoxLite output stream into the provided list."""
134
+ if stream is None:
135
+ return
136
+
137
+ try:
138
+ async for line in stream:
139
+ output_lines.append(_decode_stream_line(line))
140
+ except Exception:
141
+ # Stream collection is best-effort because cleanup paths may close
142
+ # streams abruptly after a timeout-triggered kill.
143
+ pass
144
+
145
+
146
+ async def _cancel_future(task: asyncio.Future[Any] | None) -> None:
147
+ """Cancel a task or future and suppress cleanup-related errors."""
148
+ if task is None or task.done():
149
+ return
150
+
151
+ task.cancel()
152
+ with suppress(asyncio.CancelledError, Exception):
153
+ await task
154
+
155
+
156
+ def _track_background_cleanup(task: asyncio.Task[Any]) -> None:
157
+ """Keep background cleanup tasks alive until they finish."""
158
+ _BACKGROUND_CLEANUP_TASKS.add(task)
159
+ task.add_done_callback(_BACKGROUND_CLEANUP_TASKS.discard)
160
+
161
+
162
+ async def _cleanup_box(box: Box, runtime: Boxlite) -> None:
163
+ """Best-effort asynchronous cleanup for timed-out boxes."""
164
+ with suppress(Exception):
165
+ await box.stop()
166
+ with suppress(Exception):
167
+ await runtime.remove(box.id, force=True)
168
+
169
+
170
+ async def _exec_command_with_timeout(
171
+ box: Box,
172
+ command: list[str],
173
+ timeout: int,
174
+ ) -> tuple[Any | None, str, str, bool]:
175
+ """Run a low-level BoxLite execution with explicit timeout kill semantics."""
176
+ execution = await box.exec(command[0], command[1:])
177
+
178
+ try:
179
+ stdout_stream = execution.stdout()
180
+ except Exception:
181
+ stdout_stream = None
182
+
183
+ try:
184
+ stderr_stream = execution.stderr()
185
+ except Exception:
186
+ stderr_stream = None
187
+
188
+ stdout_lines: list[str] = []
189
+ stderr_lines: list[str] = []
190
+ stdout_task = asyncio.create_task(
191
+ _collect_output_stream(stdout_stream, stdout_lines)
192
+ )
193
+ stderr_task = asyncio.create_task(
194
+ _collect_output_stream(stderr_stream, stderr_lines)
195
+ )
196
+ wait_task = asyncio.ensure_future(execution.wait())
197
+
198
+ timed_out = False
199
+ exec_result = None
200
+
201
+ try:
202
+ exec_result = await asyncio.wait_for(asyncio.shield(wait_task), timeout=timeout)
203
+ await asyncio.gather(stdout_task, stderr_task, return_exceptions=True)
204
+ except asyncio.TimeoutError:
205
+ timed_out = True
206
+ with suppress(Exception):
207
+ await execution.kill()
208
+ if wait_task.done() and not wait_task.cancelled():
209
+ with suppress(Exception):
210
+ exec_result = wait_task.result()
211
+ finally:
212
+ if not timed_out:
213
+ await _cancel_future(wait_task)
214
+ await _cancel_future(stdout_task)
215
+ await _cancel_future(stderr_task)
216
+
217
+ return exec_result, "".join(stdout_lines), "".join(stderr_lines), timed_out
218
+
219
+
220
+ async def _copy_protocol_into_box(box: Box, protocol_path: Path) -> None:
221
+ """Copy the protocol directory into the sandbox to isolate host files."""
222
+ await box.copy_in(
223
+ f"{protocol_path.absolute()}/",
224
+ f"{_WORKING_DIR}/protocol/",
225
+ _COPY_OPTIONS,
226
+ )
227
+
228
+
229
+ class AiralogyEngine:
230
+ """Protocol execution engine backed by a shared BoxLite runtime."""
231
+
232
+ def __init__(
233
+ self,
234
+ boxlite_home: str | None = None,
235
+ image: str | None = None,
236
+ rootfs_path: str | None = None,
237
+ timeout: int = 300,
238
+ memory_mib: int = 512,
239
+ cpus: int = 1,
240
+ ) -> None:
241
+ self.boxlite_home = boxlite_home
242
+ self.image = image
243
+ self.rootfs_path = rootfs_path
244
+ self.timeout = timeout
245
+ self.memory_mib = memory_mib
246
+ self.cpus = cpus
247
+ self._runtime_key: str | None = None
248
+ self._runtime: Boxlite | None = None
249
+ self._runtime_lock = threading.Lock()
250
+ self._closed = False
251
+
252
+ async def __aenter__(self) -> "AiralogyEngine":
253
+ return self
254
+
255
+ async def __aexit__(self, *args: object) -> None:
256
+ await self.close()
257
+
258
+ async def close(self) -> None:
259
+ """Release this engine's BoxLite runtime reference."""
260
+ with self._runtime_lock:
261
+ runtime_key = self._runtime_key
262
+ self._runtime_key = None
263
+ self._runtime = None
264
+ self._closed = True
265
+
266
+ if runtime_key is not None:
267
+ _release_runtime(runtime_key)
268
+
269
+ def _get_runtime(self) -> Boxlite:
270
+ with self._runtime_lock:
271
+ if self._closed:
272
+ raise ValueError("AiralogyEngine is closed")
273
+ if self._runtime is None:
274
+ self._runtime_key, self._runtime = _acquire_runtime(self.boxlite_home)
275
+ return self._runtime
276
+
277
+ async def _execute_in_sandbox(
278
+ self,
279
+ action: str,
280
+ protocol_path: str,
281
+ params: dict,
282
+ env_vars: dict | None = None,
283
+ timeout: int | None = None,
284
+ debug: bool = False,
285
+ log_file: str = "protocol_debug.log",
286
+ ) -> dict:
287
+ """Execute an action inside the BoxLite sandbox."""
288
+ image = self.image
289
+ rootfs_path = self.rootfs_path
290
+ if image is None and rootfs_path is None:
291
+ image = DEFAULT_IMAGE
292
+
293
+ proto_path = Path(protocol_path)
294
+ if not proto_path.is_dir():
295
+ raise ValueError(f"protocol_path must be a directory: {protocol_path}")
296
+ if not proto_path.joinpath("protocol.aimd").is_file():
297
+ raise ValueError(
298
+ f"protocol.aimd not found in protocol_path: {protocol_path}"
299
+ )
300
+
301
+ if rootfs_path is not None:
302
+ rootfs = Path(rootfs_path).resolve()
303
+ if not rootfs.is_dir():
304
+ raise ValueError(f"rootfs_path must be a directory: {rootfs_path}")
305
+
306
+ env_pairs = [(k, v) for k, v in (env_vars or {}).items()]
307
+ if debug:
308
+ env_pairs.append(("PROTOCOL_DEBUG", "1"))
309
+
310
+ box_options = BoxOptions(
311
+ image=image if rootfs_path is None else None,
312
+ rootfs_path=str(rootfs) if rootfs_path is not None else None,
313
+ memory_mib=self.memory_mib,
314
+ cpus=self.cpus,
315
+ working_dir=_WORKING_DIR,
316
+ env=env_pairs,
317
+ )
318
+
319
+ effective_timeout = self.timeout if timeout is None else timeout
320
+ box: Box | None = None
321
+ runtime: Boxlite | None = None
322
+ result: dict | None = None
323
+ timed_out = False
324
+ try:
325
+ runtime = self._get_runtime()
326
+ box = await runtime.create(box_options)
327
+ await box.copy_in(
328
+ _EXECUTOR_PATH,
329
+ f"{_WORKING_DIR}/",
330
+ _COPY_OPTIONS,
331
+ )
332
+ await _copy_protocol_into_box(box, proto_path)
333
+
334
+ command = [
335
+ "python",
336
+ "protocol_executor.py",
337
+ action,
338
+ "protocol",
339
+ json.dumps(params, separators=(",", ":")),
340
+ ]
341
+ exec_result, stdout, stderr, timed_out = await _exec_command_with_timeout(
342
+ box,
343
+ command,
344
+ effective_timeout,
345
+ )
346
+
347
+ if timed_out:
348
+ result = {
349
+ "success": False,
350
+ "message": f"Execution timed out after {effective_timeout} seconds",
351
+ "output": "",
352
+ }
353
+ elif exec_result is None:
354
+ result = {
355
+ "success": False,
356
+ "message": "Sandbox execution did not return a result",
357
+ "output": stderr.strip(),
358
+ }
359
+ elif exec_result.exit_code != 0:
360
+ result = {
361
+ "success": False,
362
+ "message": f"Protocol exec failed with return code {exec_result.exit_code}",
363
+ "output": stderr.strip(),
364
+ }
365
+ else:
366
+ output = stdout.strip()
367
+ try:
368
+ result = json.loads(output)
369
+ except json.JSONDecodeError:
370
+ result = {
371
+ "success": False,
372
+ "message": "Invalid JSON output from protocol executor",
373
+ "output": output,
374
+ }
375
+ except BoxliteError as e:
376
+ result = {
377
+ "success": False,
378
+ "message": f"Sandbox error: {str(e)}",
379
+ "output": "",
380
+ }
381
+ except RuntimeError as e:
382
+ result = {
383
+ "success": False,
384
+ "message": f"Sandbox error: {str(e)}",
385
+ "output": "",
386
+ }
387
+ except BaseException as e:
388
+ if not _is_pyo3_panic(e):
389
+ raise
390
+ result = {
391
+ "success": False,
392
+ "message": f"Sandbox runtime error: {str(e)}",
393
+ "output": "",
394
+ }
395
+ finally:
396
+ if box is not None:
397
+ if debug:
398
+ await _copy_out_log(box, log_file)
399
+ if timed_out and runtime is not None:
400
+ _track_background_cleanup(
401
+ asyncio.create_task(_cleanup_box(box, runtime))
402
+ )
403
+ else:
404
+ try:
405
+ await box.stop()
406
+ except BaseException as e:
407
+ if result is None or not _is_pyo3_panic(e):
408
+ raise
409
+
410
+ if result is None:
411
+ return {
412
+ "success": False,
413
+ "message": "Sandbox execution failed without a result",
414
+ "output": "",
415
+ }
416
+
417
+ return result
418
+
419
+ async def parse_protocol(
420
+ self,
421
+ protocol_path: str,
422
+ env_vars: dict | None = None,
423
+ timeout: int | None = None,
424
+ debug: bool = False,
425
+ log_file: str = "protocol_debug.log",
426
+ ) -> dict:
427
+ """Parse a protocol package and return its schema, metadata, and fields."""
428
+ return await self._execute_in_sandbox(
429
+ "parse_protocol",
430
+ protocol_path,
431
+ {},
432
+ env_vars=env_vars,
433
+ timeout=timeout,
434
+ debug=debug,
435
+ log_file=log_file,
436
+ )
437
+
438
+ async def assign_variable(
439
+ self,
440
+ protocol_path: str,
441
+ var_name: str,
442
+ dependent_data: dict,
443
+ env_vars: dict | None = None,
444
+ timeout: int | None = None,
445
+ debug: bool = False,
446
+ log_file: str = "protocol_debug.log",
447
+ ) -> dict:
448
+ """Assign a variable value using the protocol's assigner functions."""
449
+ params = {
450
+ "var_name": var_name,
451
+ "dependent_data": dependent_data,
452
+ }
453
+ return await self._execute_in_sandbox(
454
+ "assign_variable",
455
+ protocol_path,
456
+ params,
457
+ env_vars=env_vars,
458
+ timeout=timeout,
459
+ debug=debug,
460
+ log_file=log_file,
461
+ )
462
+
463
+ async def validate_variables(
464
+ self,
465
+ protocol_path: str,
466
+ variables: dict,
467
+ env_vars: dict | None = None,
468
+ timeout: int | None = None,
469
+ debug: bool = False,
470
+ log_file: str = "protocol_debug.log",
471
+ ) -> dict:
472
+ """Validate variable values against the protocol's model."""
473
+ return await self._execute_in_sandbox(
474
+ "validate_variables",
475
+ protocol_path,
476
+ variables,
477
+ env_vars=env_vars,
478
+ timeout=timeout,
479
+ debug=debug,
480
+ log_file=log_file,
481
+ )
@@ -0,0 +1,418 @@
1
+ import importlib
2
+ import importlib.util
3
+ import json
4
+ import logging
5
+ import os
6
+ import re
7
+ import sys
8
+ import tomllib
9
+ from contextlib import redirect_stdout
10
+ from datetime import timedelta
11
+ from typing import get_args, get_origin
12
+
13
+ from airalogy.assigner import DefaultAssigner
14
+ from airalogy.markdown import extract_assigner_blocks, generate_model, parse_aimd
15
+ from airalogy.markdown.errors import AimdParseError
16
+ from pydantic import TypeAdapter, ValidationError, create_model
17
+
18
+ logger = logging.getLogger("protocol_executor_logger")
19
+ logger.setLevel(logging.DEBUG)
20
+ formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
21
+
22
+ _DEBUG_LOG_PATH = "protocol_debug.log"
23
+ _debug_mode = os.environ.get("PROTOCOL_DEBUG", "0") == "1"
24
+ if _debug_mode:
25
+ _file_handler = logging.FileHandler(_DEBUG_LOG_PATH)
26
+ _file_handler.setLevel(logging.DEBUG)
27
+ _file_handler.setFormatter(formatter)
28
+ logger.addHandler(_file_handler)
29
+
30
+ timedelta_adapter = TypeAdapter(timedelta)
31
+
32
+ _PROTOCOL_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_\-]*$")
33
+
34
+
35
+ def _validate_protocol_name(protocol_name: str) -> str:
36
+ """Validate protocol_name to prevent path traversal."""
37
+ if not _PROTOCOL_NAME_RE.fullmatch(protocol_name):
38
+ raise ValueError(f"Invalid protocol_name: {protocol_name!r}")
39
+ return f"./{protocol_name}"
40
+
41
+
42
+ def deep_merge(dict1: dict, dict2: dict):
43
+ """Merge two dictionaries recursively."""
44
+ result = dict1.copy()
45
+ for key, value in dict2.items():
46
+ if key in result and isinstance(result[key], dict) and isinstance(value, dict):
47
+ result[key] = deep_merge(result[key], value)
48
+ else:
49
+ result[key] = value
50
+ return result
51
+
52
+
53
+ # custom json encoder for timedelta
54
+ class RNJSONEncoder(json.JSONEncoder):
55
+ def default(self, obj):
56
+ if isinstance(obj, timedelta):
57
+ return timedelta_adapter.dump_python(obj, mode="json")
58
+ else:
59
+ return json.JSONEncoder.default(self, obj)
60
+
61
+
62
+ class ProtocolStdoutLogger:
63
+ """Capture protocol stdout and forward it into the debug logger."""
64
+
65
+ encoding = "utf-8"
66
+
67
+ def __init__(self, enabled: bool):
68
+ self.enabled = enabled
69
+ self._buffer = ""
70
+
71
+ def write(self, value: str) -> int:
72
+ if not value:
73
+ return 0
74
+
75
+ if not self.enabled:
76
+ return len(value)
77
+
78
+ self._buffer += value
79
+ while "\n" in self._buffer:
80
+ line, self._buffer = self._buffer.split("\n", 1)
81
+ logger.debug(f"protocol stdout: {line.rstrip('\r')}")
82
+ return len(value)
83
+
84
+ def flush(self) -> None:
85
+ if self.enabled and self._buffer:
86
+ logger.debug(f"protocol stdout: {self._buffer.rstrip('\r')}")
87
+ self._buffer = ""
88
+
89
+
90
+ def import_module(module_name, force_reload=False):
91
+ importlib.invalidate_caches()
92
+
93
+ if not force_reload and module_name in sys.modules:
94
+ return sys.modules[module_name]
95
+
96
+ previous = sys.modules.pop(module_name, None)
97
+
98
+ spec = importlib.util.find_spec(module_name)
99
+ if spec is None or spec.loader is None:
100
+ logger.warning(f"module {module_name} not found")
101
+ return None
102
+
103
+ try:
104
+ module = importlib.util.module_from_spec(spec)
105
+ sys.modules[module_name] = module
106
+ spec.loader.exec_module(module)
107
+ return module
108
+ except SyntaxError as e:
109
+ sys.modules.pop(module_name, None)
110
+ filename = os.path.basename(e.filename) if e.filename else "<unknown>"
111
+ error_msg = (
112
+ f"Protocol module `{module_name.split('.')[-1]}` has syntax error: {e}"
113
+ )
114
+ error_msg += f"\nfile: {filename}, line: {e.lineno}, offset: {e.offset}"
115
+ error_msg += f"\nerror code: {e.text}"
116
+ logger.error(error_msg)
117
+ raise ImportError(error_msg) from e
118
+ except Exception as e:
119
+ sys.modules.pop(module_name, None)
120
+ error_msg = (
121
+ f"Import protocol module `{module_name.split('.')[-1]}` fail, error: {e}"
122
+ )
123
+ logger.error(error_msg)
124
+ raise ImportError(error_msg) from e
125
+
126
+
127
+ def _load_aimd_model(protocol_name: str):
128
+ """Generate and load the AIMD model module for the protocol."""
129
+ protocol_path = _validate_protocol_name(protocol_name)
130
+ try:
131
+ with open(f"{protocol_path}/protocol.aimd", encoding="utf-8") as aimd_file:
132
+ aimd = aimd_file.read()
133
+ aimd_model_code = generate_model(aimd)
134
+ with open(f"{protocol_path}/aimd_model.py", "w", encoding="utf-8") as out_file:
135
+ out_file.write(aimd_model_code)
136
+ except AimdParseError as e:
137
+ raise ValueError(f"Error parsing protocol.aimd: {e}") from e
138
+
139
+ model = import_module(f"{protocol_name}.aimd_model", force_reload=True)
140
+ if model is None or not hasattr(model, "VarModel"):
141
+ raise ValueError(f"Failed to load AIMD model for protocol `{protocol_name}`")
142
+ return model
143
+
144
+
145
+ def parse_protocol(protocol_name: str):
146
+ protocol_path = _validate_protocol_name(protocol_name)
147
+ # check protocol.aimd file
148
+ if not os.path.isfile(f"{protocol_path}/protocol.aimd"):
149
+ raise ValueError("protocol.aimd file not found in package")
150
+
151
+ protocol_toml_path = f"{protocol_path}/protocol.toml"
152
+ # check protocol.toml file
153
+ if not os.path.isfile(protocol_toml_path):
154
+ raise ValueError("protocol.toml file not found in package")
155
+
156
+ try:
157
+ with open(f"{protocol_path}/protocol.aimd", encoding="utf-8") as aimd_file:
158
+ aimd = aimd_file.read()
159
+ fields = parse_aimd(aimd)["templates"]
160
+ aimd_model_code = generate_model(aimd)
161
+ with open(f"{protocol_path}/aimd_model.py", "w", encoding="utf-8") as out_file:
162
+ out_file.write(aimd_model_code)
163
+ _ensure_assigner(protocol_name, aimd=aimd)
164
+ except AimdParseError as e:
165
+ raise ValueError(f"Error parsing protocol.aimd: {e}") from e
166
+ var_names = {var["name"] for var in fields["var"]}
167
+ steps = {step["name"] for step in fields["step"]}
168
+ checks = {check["name"] for check in fields["check"]}
169
+
170
+ # read metadata from protocol.toml
171
+ try:
172
+ with open(protocol_toml_path, "rb") as f:
173
+ meta_data = tomllib.load(f)
174
+ except Exception as e:
175
+ raise ValueError(f"Error parsing protocol.toml: {e}") from e
176
+ if "airalogy_protocol" not in meta_data:
177
+ raise ValueError(
178
+ "Invalid protocol.toml, error: airalogy_protocol not found in protocol.toml"
179
+ )
180
+ meta_data = meta_data["airalogy_protocol"]
181
+ # check id, name, version
182
+ if "id" not in meta_data:
183
+ raise ValueError("Invalid protocol.toml, error: id not found in protocol.toml")
184
+ if "name" not in meta_data:
185
+ raise ValueError(
186
+ "Invalid protocol.toml, error: name not found in protocol.toml"
187
+ )
188
+ if "version" not in meta_data:
189
+ raise ValueError(
190
+ "Invalid protocol.toml, error: version not found in protocol.toml"
191
+ )
192
+
193
+ # read env vars from .env file
194
+ env_vars_str = ""
195
+ env_file = f"{protocol_path}/.env"
196
+ if os.path.isfile(env_file):
197
+ with open(env_file, encoding="utf-8") as f:
198
+ env_vars_str = f.read()
199
+
200
+ schema = {
201
+ "steps": {},
202
+ "vars": {},
203
+ "checks": {},
204
+ }
205
+
206
+ # load aimd model
207
+ aimd_model = import_module(f"{protocol_name}.aimd_model", force_reload=True)
208
+ if aimd_model and hasattr(aimd_model, "VarModel"):
209
+ aimd_schema = aimd_model.VarModel.model_json_schema()
210
+ else:
211
+ aimd_schema = {"type": "object", "required": [], "properties": {}}
212
+
213
+ # load var model
214
+ var_model = import_module(f"{protocol_name}.model")
215
+ if var_model and hasattr(var_model, "VarModel"):
216
+ model_schema = var_model.VarModel.model_json_schema()
217
+ # check model schema properties should be defined in AIMD
218
+ errors = []
219
+ for key in model_schema["properties"]:
220
+ if key not in var_names:
221
+ errors.append(f"Model field `{key}` not defined in AIMD file")
222
+ if errors:
223
+ raise ValueError("\n".join(errors))
224
+ else:
225
+ model_schema = {}
226
+
227
+ schema["vars"] = deep_merge(aimd_schema, model_schema)
228
+
229
+ assigners = {}
230
+ assigner_graph = None
231
+ assigner = import_module(f"{protocol_name}.assigner")
232
+ if assigner:
233
+ if hasattr(assigner, "Assigner"):
234
+ assigners = assigner.Assigner.all_assigned_fields()
235
+ assigner_graph = assigner.Assigner.export_dependency_graph_to_dict()
236
+ else:
237
+ assigners = DefaultAssigner.all_assigned_fields()
238
+ assigner_graph = DefaultAssigner.export_dependency_graph_to_dict()
239
+
240
+ errors = []
241
+ for k, v in assigners.items():
242
+ field_name = k.split(".")[0] if "." in k else k
243
+ if (
244
+ field_name not in var_names
245
+ and field_name not in steps
246
+ and field_name not in checks
247
+ ):
248
+ errors.append(f"Assigner field {k} not defined in protocol.aimd file")
249
+ for j in v["dependent_fields"]:
250
+ dep_name = j.split(".")[0] if "." in j else j
251
+ if (
252
+ dep_name not in var_names
253
+ and dep_name not in steps
254
+ and dep_name not in checks
255
+ ):
256
+ errors.append(
257
+ f"Assigner dependent field {j} not defined in protocol.aimd file"
258
+ )
259
+ if errors:
260
+ raise ValueError("\n".join(errors))
261
+
262
+ return {
263
+ "meta_data": meta_data,
264
+ "fields": fields,
265
+ "aimd": aimd,
266
+ "json_schema": schema,
267
+ "assigners": assigners,
268
+ "assigner_graph": assigner_graph,
269
+ "env_vars": env_vars_str,
270
+ }
271
+
272
+
273
+ def _ensure_assigner(protocol_name: str, aimd: str | None = None) -> None:
274
+ """Generate assigner.py from protocol.aimd if it doesn't exist."""
275
+ protocol_path = _validate_protocol_name(protocol_name)
276
+ assigner_path = f"{protocol_path}/assigner.py"
277
+ if not os.path.isfile(assigner_path):
278
+ try:
279
+ if aimd is None:
280
+ with open(
281
+ f"{protocol_path}/protocol.aimd", encoding="utf-8"
282
+ ) as aimd_file:
283
+ aimd = aimd_file.read()
284
+ assigner_code_blocks = extract_assigner_blocks(aimd)
285
+ if len(assigner_code_blocks) > 0:
286
+ with open(assigner_path, "w", encoding="utf-8") as out_file:
287
+ out_file.write("\n\n".join(assigner_code_blocks))
288
+ except AimdParseError as e:
289
+ raise ValueError(f"Error parsing protocol.aimd: {e}") from e
290
+
291
+
292
+ def assign_variable(protocol_name: str, params: dict) -> dict:
293
+ _validate_protocol_name(protocol_name)
294
+ _ensure_assigner(protocol_name)
295
+
296
+ # load assigner
297
+ assigner_module = import_module(f"{protocol_name}.assigner")
298
+ if assigner_module is None:
299
+ raise ValueError("Protocol Package does not have assigner")
300
+
301
+ if hasattr(assigner_module, "Assigner"):
302
+ assigner = assigner_module.Assigner
303
+ else:
304
+ assigner = DefaultAssigner
305
+
306
+ # load aimd_model
307
+ aimd_model = _load_aimd_model(protocol_name)
308
+ fields = aimd_model.VarModel.model_fields
309
+
310
+ # load model
311
+ var_model = import_module(f"{protocol_name}.model")
312
+ if var_model is not None and hasattr(var_model, "VarModel"):
313
+ fields = deep_merge(fields, var_model.VarModel.model_fields)
314
+
315
+ try:
316
+ # dependent_data validation and type convert
317
+ attrs = {}
318
+ for k, v in params["dependent_data"].items():
319
+ if k in fields:
320
+ attrs[k] = (fields[k].annotation, fields[k].default)
321
+ elif "." in k:
322
+ var_table_name, sub_var_name = k.split(".", 1)
323
+ if var_table_name not in fields:
324
+ raise ValueError(f"Var: {var_table_name} not defined in VarModel")
325
+ if get_origin(fields[var_table_name].annotation) is not list:
326
+ raise ValueError(
327
+ f"Var table variable: {var_table_name} must be a list"
328
+ )
329
+ table_type = get_args(fields[var_table_name].annotation)[0]
330
+ if sub_var_name in table_type.model_fields:
331
+ attrs[k] = (
332
+ table_type.model_fields[sub_var_name].annotation,
333
+ table_type.model_fields[sub_var_name].default,
334
+ )
335
+ else:
336
+ attrs[k] = (str, ...)
337
+ else:
338
+ attrs[k] = (str, ...)
339
+ ParamsModel = create_model("ParamsModel", **attrs)
340
+ logger.info(f"ParamsModel: {ParamsModel.model_json_schema()}")
341
+ try:
342
+ dependent_data = ParamsModel(**params["dependent_data"])
343
+ except ValidationError as e:
344
+ raise ValueError(f"Dependent data validation failed: {e}") from e
345
+ res = assigner.assign(params["var_name"], dict(dependent_data))
346
+ return res.model_dump()
347
+ except ValueError:
348
+ raise
349
+ except Exception as e:
350
+ raise ValueError(f"Assigner function execute fail, error: {e}") from e
351
+
352
+
353
+ def validate_variables(protocol_name: str, variables: dict) -> dict:
354
+ _validate_protocol_name(protocol_name)
355
+ data = {"data": variables}
356
+
357
+ # validate by aimd model
358
+ aimd_model = _load_aimd_model(protocol_name)
359
+ try:
360
+ aimd_model.VarModel(**variables)
361
+ except ValidationError as exc:
362
+ data["errors"] = exc.errors()
363
+
364
+ # validate by custom model
365
+ model = import_module(f"{protocol_name}.model")
366
+ if model is not None and hasattr(model, "VarModel"):
367
+ try:
368
+ model.VarModel(**variables)
369
+ except ValidationError as exc:
370
+ existing = data.get("errors", [])
371
+ existing.extend(exc.errors())
372
+ data["errors"] = existing
373
+
374
+ return data
375
+
376
+
377
+ def main(action: str, protocol_name: str, input_params: str):
378
+ logger.info(
379
+ f"action: {action}, protocol_name: {protocol_name}, input_params: {input_params}"
380
+ )
381
+ stdout_capture = ProtocolStdoutLogger(enabled=_debug_mode)
382
+ try:
383
+ with redirect_stdout(stdout_capture):
384
+ params = json.loads(input_params)
385
+
386
+ if action == "parse_protocol":
387
+ result = parse_protocol(protocol_name)
388
+ elif action == "assign_variable":
389
+ result = assign_variable(protocol_name, params)
390
+ elif action == "validate_variables":
391
+ result = validate_variables(protocol_name, params)
392
+ else:
393
+ raise ValueError(f"Unknown action: {action}")
394
+
395
+ result = {
396
+ "success": True,
397
+ "message": "",
398
+ "data": result,
399
+ }
400
+ output = json.dumps(
401
+ result, cls=RNJSONEncoder, separators=(",", ":"), ensure_ascii=False
402
+ )
403
+ except Exception as e:
404
+ logger.exception(e)
405
+ result = {"success": False, "message": repr(e), "error_type": type(e).__name__}
406
+ output = json.dumps(result, separators=(",", ":"), ensure_ascii=False)
407
+ finally:
408
+ stdout_capture.flush()
409
+
410
+ logger.info(f"output: {output}")
411
+ print(output)
412
+
413
+
414
+ if __name__ == "__main__":
415
+ action = sys.argv[1]
416
+ protocol_name = sys.argv[2]
417
+ params = sys.argv[3] if len(sys.argv) > 3 else "{}"
418
+ main(action, protocol_name, params)