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,527 @@
1
+ """Optional ReAct agent for Levier runtimes.
2
+
3
+ The loop lives in `levier_agent_core`; this module only translates between
4
+ RunContext and the loop contract.
5
+
6
+ Copyright 2026 The Levier Authors.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import Any, Sequence
12
+
13
+ from levier_runtime import RunContext
14
+
15
+ from levier_agent_core import (
16
+ AgentCore,
17
+ LLMResponse as CoreLLMResponse,
18
+ Message as CoreMessage,
19
+ ModelRef,
20
+ ProviderFailure,
21
+ RunSpec,
22
+ ToolCall as CoreToolCall,
23
+ ToolResult as CoreToolResult,
24
+ ToolSpec as CoreToolSpec,
25
+ Usage,
26
+ )
27
+ from levier_agent_core.events import (
28
+ ErrorEvent,
29
+ MessageCompleted,
30
+ MessageDelta,
31
+ ToolFinished,
32
+ ToolStarted,
33
+ UsageEvent,
34
+ )
35
+ from levier_runtime.ids import new_ulid
36
+ from levier_runtime.llm.base import (
37
+ DeltaCallback,
38
+ LLMError,
39
+ LLMProvider,
40
+ LLMResponse,
41
+ Message,
42
+ ModelConfig,
43
+ ToolCall,
44
+ ToolSpec,
45
+ )
46
+ from levier_runtime.react.checkpoint import CheckpointError, CheckpointState, capture
47
+ from levier_runtime.tools.base import ToolProvider, ToolResult, as_tool_provider
48
+
49
+ _DEFAULT_MAX_STEPS = 32
50
+ _DEFAULT_STEP_TIMEOUT_MS = 120_000
51
+ _DEFAULT_TOOL_TIMEOUT_MS = 60_000
52
+
53
+
54
+ class ReactAgent:
55
+ """Implement the standard ReAct loop for a Levier Runtime."""
56
+
57
+ def __init__(
58
+ self,
59
+ provider: LLMProvider,
60
+ tools: ToolProvider | object | None = None,
61
+ *,
62
+ default_step_timeout_ms: int = _DEFAULT_STEP_TIMEOUT_MS,
63
+ default_tool_timeout_ms: int = _DEFAULT_TOOL_TIMEOUT_MS,
64
+ ) -> None:
65
+ self.provider = provider
66
+ self._uses_context_tools = tools is None
67
+ self.tools = _ContextToolProvider() if tools is None else as_tool_provider(tools)
68
+ self.default_step_timeout_ms = default_step_timeout_ms
69
+ self.default_tool_timeout_ms = default_tool_timeout_ms
70
+
71
+ async def run(self, ctx: RunContext) -> str:
72
+ """Adapt one RunContext to the agent core loop."""
73
+ max_steps = max(1, _int_param(ctx.params, "max_steps", _DEFAULT_MAX_STEPS))
74
+ step_timeout_ms = _int_param(
75
+ ctx.params,
76
+ "step_timeout_ms",
77
+ self.default_step_timeout_ms,
78
+ )
79
+ tool_timeout_ms = ctx.timeouts.tool_ms or self.default_tool_timeout_ms
80
+
81
+ messages = [_message_from_context(message) for message in ctx.input]
82
+ start_step = 1
83
+ resume: CheckpointState | None = None
84
+ if ctx.resume_from:
85
+ try:
86
+ resume = CheckpointState.decode(ctx.resume_from)
87
+ except CheckpointError as exc:
88
+ await self._emit_error(ctx, "INVALID_CHECKPOINT", str(exc))
89
+ return "failed"
90
+ if resume.runtime_name != ctx.runtime_name:
91
+ await self._emit_error(
92
+ ctx,
93
+ "CHECKPOINT_RUNTIME_MISMATCH",
94
+ f"checkpoint runtime {resume.runtime_name!r} does not match {ctx.runtime_name!r}",
95
+ )
96
+ return "failed"
97
+ if resume.session_id != ctx.session_id:
98
+ await self._emit_error(
99
+ ctx,
100
+ "CHECKPOINT_SESSION_MISMATCH",
101
+ f"checkpoint session {resume.session_id!r} does not match {ctx.session_id!r}",
102
+ )
103
+ return "failed"
104
+ if resume.messages:
105
+ messages = list(resume.messages)
106
+ start_step = max(1, resume.step + 1)
107
+
108
+ try:
109
+ tools = [_tool_from_context(tool) for tool in ctx.tools]
110
+ model = _model_from_context(ctx.model)
111
+ if model is None:
112
+ await self._emit_error(ctx, "MODEL_REQUIRED", "run input has no model")
113
+ return "failed"
114
+ except Exception as exc:
115
+ await self._emit_error(ctx, "INVALID_RUN_INPUT", str(exc))
116
+ return "failed"
117
+
118
+ result = None
119
+ saved_on_cancel = False
120
+ try:
121
+ tools.extend(await self.tools.open(ctx))
122
+ spec = RunSpec(
123
+ run_id=ctx.run_id,
124
+ start_step=start_step,
125
+ messages=[_to_core_message(message) for message in messages],
126
+ tools=[_to_core_tool(tool) for tool in tools],
127
+ model=ModelRef(
128
+ provider=model.provider,
129
+ model=model.model,
130
+ params=dict(model.params),
131
+ ),
132
+ max_steps=max_steps,
133
+ step_timeout_ms=step_timeout_ms,
134
+ tool_timeout_ms=tool_timeout_ms,
135
+ session_id=ctx.session_id or "",
136
+ )
137
+ core = AgentCore(
138
+ _ProviderAdapter(self.provider, model),
139
+ _ToolAdapter(self.tools, ctx, tool_timeout_ms),
140
+ new_id=new_ulid,
141
+ )
142
+
143
+ async def on_step_end(core_messages: Sequence[CoreMessage], step: int) -> None:
144
+ if ctx.session_id:
145
+ await self._save_checkpoint(
146
+ ctx,
147
+ [_to_react_message(message) for message in core_messages],
148
+ step,
149
+ )
150
+
151
+ async def on_cancel(core_messages: Sequence[CoreMessage], step: int) -> None:
152
+ nonlocal saved_on_cancel
153
+ if ctx.session_id and step > 0:
154
+ try:
155
+ await self._save_checkpoint(
156
+ ctx,
157
+ [_to_react_message(message) for message in core_messages],
158
+ step,
159
+ )
160
+ saved_on_cancel = True
161
+ except Exception:
162
+ pass
163
+
164
+ result = await core.run(
165
+ spec,
166
+ lambda event: _emit_core_event(
167
+ ctx,
168
+ event,
169
+ emit_tool_events=not self._uses_context_tools,
170
+ ),
171
+ abort=_CtxAbort(ctx),
172
+ on_step_end=on_step_end,
173
+ on_cancel=on_cancel,
174
+ )
175
+ finally:
176
+ if (
177
+ not saved_on_cancel
178
+ and ctx.session_id
179
+ and result is not None
180
+ and result.steps > 0
181
+ ):
182
+ try:
183
+ await self._save_checkpoint(
184
+ ctx,
185
+ [_to_react_message(message) for message in result.messages],
186
+ result.steps,
187
+ )
188
+ except Exception:
189
+ pass
190
+ try:
191
+ await self.tools.close(ctx)
192
+ except Exception:
193
+ pass
194
+ return result.status if result is not None else "failed"
195
+
196
+ async def _save_checkpoint(
197
+ self,
198
+ ctx: RunContext,
199
+ messages: Sequence[Message],
200
+ step: int,
201
+ ) -> None:
202
+ if not ctx.session_id:
203
+ return
204
+ state = capture(
205
+ session_id=ctx.session_id,
206
+ run_id=ctx.run_id,
207
+ attempt=ctx.attempt,
208
+ runtime_name=ctx.runtime_name,
209
+ step=step,
210
+ messages=list(messages),
211
+ last_event_seq=0,
212
+ )
213
+ await ctx.checkpoint(state.encode())
214
+
215
+ async def __call__(self, ctx: RunContext) -> str:
216
+ """Allow the agent to be used as a RunManager runner."""
217
+ return await self.run(ctx)
218
+
219
+ async def _emit_error(
220
+ self,
221
+ ctx: RunContext,
222
+ code: str,
223
+ message: str,
224
+ *,
225
+ retryable: bool = False,
226
+ ) -> None:
227
+ await ctx.error(code, message, retryable=retryable)
228
+
229
+
230
+ class _ContextToolProvider:
231
+ """Use the Runtime SDK toolbox for MCP and the bridge for local tools."""
232
+
233
+ async def open(self, ctx: RunContext) -> Sequence[ToolSpec]:
234
+ toolbox = await ctx.toolbox()
235
+ return [
236
+ ToolSpec(
237
+ name=tool.name,
238
+ description=tool.description,
239
+ input_schema_json=tool.schema_json,
240
+ )
241
+ for tool in toolbox
242
+ if tool.scope == "mcp"
243
+ ]
244
+
245
+ async def call(
246
+ self,
247
+ ctx: RunContext,
248
+ call: ToolCall,
249
+ timeout_ms: int,
250
+ ) -> ToolResult:
251
+ toolbox = await ctx.toolbox()
252
+ tool = toolbox.find(call.name)
253
+ if tool is not None and tool.scope == "mcp":
254
+ result = await toolbox.call(call.name, call.arguments_json)
255
+ else:
256
+ result = await ctx.call_tool(
257
+ call.name,
258
+ call.arguments_json,
259
+ timeout_ms=timeout_ms,
260
+ )
261
+ return ToolResult(
262
+ ok=result.ok,
263
+ result_json=result.result_json,
264
+ error_code=result.error_code,
265
+ error_message=result.error_message,
266
+ retryable=result.retryable,
267
+ )
268
+
269
+ async def close(self, ctx: RunContext) -> None:
270
+ await ctx.close_toolbox()
271
+
272
+
273
+ class _CtxAbort:
274
+ def __init__(self, ctx: RunContext) -> None:
275
+ self.ctx = ctx
276
+
277
+ def is_set(self) -> bool:
278
+ return self.ctx.cancelled
279
+
280
+
281
+ class _ProviderAdapter:
282
+ def __init__(self, provider: LLMProvider, model: ModelConfig) -> None:
283
+ self.provider = provider
284
+ self.model = model
285
+
286
+ async def complete(
287
+ self,
288
+ messages: Sequence[CoreMessage],
289
+ tools: Sequence[CoreToolSpec],
290
+ model: ModelRef,
291
+ *,
292
+ on_delta: DeltaCallback | None = None,
293
+ ) -> CoreLLMResponse:
294
+ try:
295
+ response = await self.provider.complete(
296
+ [_to_react_message(message) for message in messages],
297
+ [_to_react_tool(tool) for tool in tools],
298
+ self.model,
299
+ on_delta=on_delta,
300
+ )
301
+ except LLMError as exc:
302
+ raise ProviderFailure(exc.code, str(exc), retryable=exc.retryable) from exc
303
+ except Exception as exc: # noqa: BLE001 - adapter boundary
304
+ raise ProviderFailure("LLM_ERROR", str(exc)) from exc
305
+ return _to_core_response(response)
306
+
307
+
308
+ class _ToolAdapter:
309
+ def __init__(self, tools: ToolProvider, ctx: RunContext, timeout_ms: int) -> None:
310
+ self.tools = tools
311
+ self.ctx = ctx
312
+ self.timeout_ms = timeout_ms
313
+
314
+ async def call(self, call: CoreToolCall) -> CoreToolResult:
315
+ result = await self.tools.call(
316
+ self.ctx,
317
+ ToolCall(
318
+ call_id=call.call_id,
319
+ name=call.name,
320
+ arguments_json=call.arguments_json,
321
+ invocation_id=call.invocation_id,
322
+ ),
323
+ self.timeout_ms,
324
+ )
325
+ return CoreToolResult(
326
+ ok=result.ok,
327
+ result_json=result.result_json,
328
+ error_code=result.error_code,
329
+ error_message=result.error_message,
330
+ retryable=result.retryable,
331
+ )
332
+
333
+
334
+ async def _emit_core_event(
335
+ ctx: RunContext,
336
+ event: Any,
337
+ *,
338
+ emit_tool_events: bool = True,
339
+ ) -> None:
340
+ if isinstance(event, MessageDelta):
341
+ await ctx.emit(
342
+ "MESSAGE_DELTA",
343
+ {"message_id": event.message_id, "delta": event.delta, "step": event.step},
344
+ ephemeral=True,
345
+ )
346
+ return
347
+ if isinstance(event, MessageCompleted):
348
+ data: dict[str, Any] = {
349
+ "message_id": event.message_id,
350
+ "role": "assistant",
351
+ "content": event.content,
352
+ "step": event.step,
353
+ }
354
+ if event.model:
355
+ data["model"] = event.model
356
+ if event.tool_calls:
357
+ data["tool_calls"] = [
358
+ {
359
+ "call_id": call.call_id,
360
+ "tool_name": call.name,
361
+ "arguments_json": call.arguments_json,
362
+ }
363
+ for call in event.tool_calls
364
+ ]
365
+ await ctx.emit("MESSAGE_COMPLETED", data)
366
+ return
367
+ if isinstance(event, UsageEvent):
368
+ await ctx.emit("USAGE", event.usage.to_dict())
369
+ return
370
+ if isinstance(event, ToolStarted):
371
+ if not emit_tool_events:
372
+ return
373
+ await ctx.emit(
374
+ "TOOL_CALL_BEGIN",
375
+ {
376
+ "invocation_id": event.invocation_id,
377
+ "tool_name": event.tool_name,
378
+ "arguments_json": event.arguments_json,
379
+ },
380
+ )
381
+ return
382
+ if isinstance(event, ToolFinished):
383
+ if not emit_tool_events:
384
+ return
385
+ data = {
386
+ "invocation_id": event.invocation_id,
387
+ "tool_name": event.tool_name,
388
+ "ok": event.ok,
389
+ "duration_ms": event.duration_ms,
390
+ }
391
+ if event.ok:
392
+ data["result_json"] = event.result_json
393
+ else:
394
+ data["error_code"] = event.error_code
395
+ data["error_message"] = event.error_message
396
+ data["retryable"] = event.retryable
397
+ await ctx.emit("TOOL_CALL_END", data)
398
+ return
399
+ if isinstance(event, ErrorEvent):
400
+ code = "MAX_STEPS_EXCEEDED" if event.code == "MAX_STEPS" else event.code
401
+ await ctx.emit(
402
+ "ERROR",
403
+ {"code": code, "message": event.message, "retryable": event.retryable},
404
+ )
405
+
406
+
407
+ def _to_core_message(message: Message) -> CoreMessage:
408
+ return CoreMessage(
409
+ role=message.role,
410
+ content=message.content,
411
+ name=message.name,
412
+ tool_call_id=message.tool_call_id,
413
+ tool_calls=tuple(
414
+ CoreToolCall(
415
+ call_id=call.call_id,
416
+ name=call.name,
417
+ arguments_json=call.arguments_json,
418
+ invocation_id=call.invocation_id,
419
+ )
420
+ for call in message.tool_calls
421
+ ),
422
+ )
423
+
424
+
425
+ def _to_react_message(message: CoreMessage) -> Message:
426
+ return Message(
427
+ role=message.role,
428
+ content=message.content,
429
+ name=message.name,
430
+ tool_call_id=message.tool_call_id,
431
+ tool_calls=tuple(
432
+ ToolCall(
433
+ call_id=call.call_id,
434
+ name=call.name,
435
+ arguments_json=call.arguments_json,
436
+ invocation_id=call.invocation_id,
437
+ )
438
+ for call in message.tool_calls
439
+ ),
440
+ )
441
+
442
+
443
+ def _to_core_tool(tool: ToolSpec) -> CoreToolSpec:
444
+ return CoreToolSpec(
445
+ name=tool.name,
446
+ description=tool.description,
447
+ input_schema_json=tool.input_schema_json,
448
+ )
449
+
450
+
451
+ def _to_react_tool(tool: CoreToolSpec) -> ToolSpec:
452
+ return ToolSpec(
453
+ name=tool.name,
454
+ description=tool.description,
455
+ input_schema_json=tool.input_schema_json,
456
+ )
457
+
458
+
459
+ def _to_core_response(response: LLMResponse) -> CoreLLMResponse:
460
+ return CoreLLMResponse(
461
+ content=response.content,
462
+ tool_calls=[
463
+ CoreToolCall(
464
+ call_id=call.call_id,
465
+ name=call.name,
466
+ arguments_json=call.arguments_json,
467
+ invocation_id=call.invocation_id,
468
+ )
469
+ for call in response.tool_calls
470
+ ],
471
+ usage=_to_core_usage(response.usage),
472
+ model=response.model,
473
+ )
474
+
475
+
476
+ def _to_core_usage(raw: dict[str, int]) -> Usage:
477
+ input_tokens = int(raw.get("input_tokens", raw.get("prompt_tokens", 0)))
478
+ output_tokens = int(raw.get("output_tokens", raw.get("completion_tokens", 0)))
479
+ return Usage(
480
+ input_tokens=input_tokens,
481
+ output_tokens=output_tokens,
482
+ total_tokens=int(raw.get("total_tokens", input_tokens + output_tokens)),
483
+ cache_read_tokens=int(raw.get("cache_read_tokens", raw.get("prompt_cache_hit_tokens", 0))),
484
+ cache_write_tokens=int(raw.get("cache_write_tokens", 0)),
485
+ )
486
+
487
+
488
+ def _int_param(params: dict[str, Any], name: str, default: int) -> int:
489
+ value = params.get(name)
490
+ if isinstance(value, bool):
491
+ return default
492
+ if isinstance(value, (int, float)):
493
+ return int(value)
494
+ if isinstance(value, str):
495
+ try:
496
+ return int(value)
497
+ except ValueError:
498
+ return default
499
+ return default
500
+
501
+
502
+ def _message_from_context(message: Any) -> Message:
503
+ return Message(
504
+ role=message.role,
505
+ content=message.content,
506
+ name=message.name,
507
+ )
508
+
509
+
510
+ def _tool_from_context(tool: Any) -> ToolSpec:
511
+ return ToolSpec(
512
+ name=tool.name,
513
+ description=tool.description,
514
+ input_schema_json=tool.input_schema_json,
515
+ )
516
+
517
+
518
+ def _model_from_context(model: Any) -> ModelConfig | None:
519
+ if model is None:
520
+ return None
521
+ return ModelConfig(
522
+ provider=model.provider,
523
+ model=model.model,
524
+ api_key=model.api_key,
525
+ base_url=model.base_url,
526
+ params=dict(model.params),
527
+ )