agent0-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,433 @@
1
+ """OpenAI SDK integration and OpenAI-compatible Responses streaming backend."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import inspect
7
+ import sys
8
+ from collections.abc import Callable
9
+ from contextlib import suppress
10
+ from typing import Any
11
+
12
+ from openai import APIConnectionError, APITimeoutError, AsyncOpenAI
13
+
14
+ from .backend import ModelRequest
15
+ from .events import EventEmitter
16
+ from .responses import (
17
+ RAW_ITEMS_KEY,
18
+ ResponseTurn,
19
+ output_text,
20
+ plain_item,
21
+ portable_history,
22
+ public_call,
23
+ raw_state,
24
+ reasoning_text,
25
+ request_input,
26
+ response_status,
27
+ response_tools,
28
+ response_usage,
29
+ )
30
+ from .types import AgentInterrupted, ModelTurn, ToolCall
31
+
32
+ RETRY_STATUS = frozenset({408, 409, 425, 429, 500, 502, 503, 504})
33
+ FAILOVER_STATUS = frozenset({401, 403, 404})
34
+ OVERFLOW_STATUS = frozenset({400, 413, 422})
35
+ RETRY_SLEEPS = (0.5, 1.5, 3.0)
36
+ STREAM_CLOSE_TIMEOUT = 2.0
37
+
38
+
39
+ async def emit_callback(cb: Callable[..., Any] | None, *args: Any) -> None:
40
+ if cb and asyncio.iscoroutine(maybe := cb(*args)):
41
+ await maybe
42
+
43
+
44
+ class RetryableResponseError(Exception):
45
+ """Failed before any output, so the request can safely be replayed."""
46
+
47
+ def __init__(self, cause: BaseException) -> None:
48
+ self.cause = cause
49
+ super().__init__(str(cause))
50
+
51
+
52
+ _RETRY_ERRORS = frozenset(
53
+ {
54
+ "APIConnectionError",
55
+ "APITimeoutError",
56
+ "RateLimitError",
57
+ "InternalServerError",
58
+ "ServiceUnavailableError",
59
+ "BadGatewayError",
60
+ }
61
+ )
62
+ _TRANSIENT_ERRORS = _RETRY_ERRORS | {"APIConnectionError", "APITimeoutError"}
63
+
64
+
65
+ def is_retryable_response_error(exc: BaseException) -> bool:
66
+ status = getattr(exc, "status_code", None)
67
+ if isinstance(status, int):
68
+ return status in RETRY_STATUS
69
+ if type(exc).__name__ in _RETRY_ERRORS or any(
70
+ cls.__name__ in _TRANSIENT_ERRORS for cls in type(exc).__mro__
71
+ ):
72
+ return True
73
+ return "overloaded" in f"{exc} {getattr(exc, 'body', '')}".lower()
74
+
75
+
76
+ def can_failover_response_error(exc: BaseException) -> bool:
77
+ """Auth/model errors may fail over; transport errors retry locally first."""
78
+
79
+ if isinstance(exc, (APIConnectionError, APITimeoutError)):
80
+ return False
81
+ return is_retryable_response_error(exc) or getattr(exc, "status_code", None) in FAILOVER_STATUS
82
+
83
+
84
+ def is_context_overflow(exc: BaseException) -> bool:
85
+ if getattr(exc, "status_code", None) not in OVERFLOW_STATUS:
86
+ return False
87
+ text = f"{exc} {getattr(exc, 'body', '')}".lower()
88
+ return any(
89
+ key in text
90
+ for key in (
91
+ "context_length",
92
+ "context length",
93
+ "maximum context",
94
+ "too many tokens",
95
+ "prompt is too long",
96
+ "input is too long",
97
+ )
98
+ )
99
+
100
+
101
+ def is_tool_history_error(exc: BaseException) -> bool:
102
+ """Some compatible Responses backends reject valid raw tool-call replay."""
103
+
104
+ if getattr(exc, "status_code", None) != 400:
105
+ return False
106
+ text = f"{exc} {getattr(exc, 'body', '')}".lower()
107
+ return "tool_call" in text and (
108
+ "must be followed by tool messages" in text or "did not have response messages" in text
109
+ )
110
+
111
+
112
+ async def _open_stream(client: AsyncOpenAI, kwargs: dict[str, Any]) -> Any:
113
+ try:
114
+ return await client.responses.create(**kwargs)
115
+ except (asyncio.CancelledError, KeyboardInterrupt) as e:
116
+ raise AgentInterrupted() from e
117
+
118
+
119
+ def _consume_close_result(task: asyncio.Task) -> None:
120
+ if not task.cancelled():
121
+ task.exception()
122
+
123
+
124
+ async def stream_response_once(
125
+ client: AsyncOpenAI,
126
+ kwargs: dict[str, Any],
127
+ *,
128
+ on_delta,
129
+ on_thinking,
130
+ on_answer_to_thinking,
131
+ on_finish,
132
+ close_timeout: float = STREAM_CLOSE_TIMEOUT,
133
+ ) -> ResponseTurn:
134
+ """Read one Responses stream into a provider-neutral ``ResponseTurn``."""
135
+
136
+ try:
137
+ stream = await _open_stream(client, kwargs)
138
+ except AgentInterrupted:
139
+ raise
140
+ except Exception as e:
141
+ raise RetryableResponseError(e) from e
142
+ parts: list[str] = []
143
+ output: list[dict[str, Any]] = []
144
+ saw_tools = emitted = False
145
+ response = None
146
+ try:
147
+ async for event in stream:
148
+ kind = getattr(event, "type", "")
149
+ if kind == "response.output_item.done":
150
+ item = plain_item(event.item)
151
+ output.append(item)
152
+ if item.get("type") == "function_call":
153
+ if not saw_tools:
154
+ saw_tools = True
155
+ await emit_callback(on_answer_to_thinking)
156
+ elif item.get("type") == "message":
157
+ text = output_text([item])
158
+ if text and text != "".join(parts):
159
+ emitted = True
160
+ parts.append(text)
161
+ await emit_callback(on_thinking if saw_tools else on_delta, text)
162
+ elif (
163
+ item.get("type") == "reasoning"
164
+ and not emitted
165
+ and (text := reasoning_text(item))
166
+ ):
167
+ emitted = True
168
+ await emit_callback(on_thinking, text)
169
+ elif kind in (
170
+ "response.reasoning_text.delta",
171
+ "response.reasoning_summary_text.delta",
172
+ ):
173
+ if text := getattr(event, "delta", ""):
174
+ emitted = True
175
+ await emit_callback(on_thinking, text)
176
+ elif kind == "response.output_text.delta":
177
+ if text := getattr(event, "delta", ""):
178
+ emitted = True
179
+ parts.append(text)
180
+ await emit_callback(on_thinking if saw_tools else on_delta, text)
181
+ elif kind in ("response.completed", "response.incomplete"):
182
+ response = event.response
183
+ final_output = [
184
+ plain_item(item) for item in getattr(response, "output", None) or []
185
+ ]
186
+ if final_output:
187
+ output = final_output
188
+ if not parts and (text := output_text(output)):
189
+ parts.append(text)
190
+ emitted = True
191
+ await emit_callback(on_thinking if saw_tools else on_delta, text)
192
+ finish, _ = response_status(response)
193
+ await emit_callback(on_finish, finish)
194
+ elif kind == "response.failed":
195
+ response = event.response
196
+ error = getattr(response, "error", None)
197
+ raise RuntimeError(
198
+ getattr(error, "message", None) or "Responses API request failed"
199
+ )
200
+ elif kind == "response.error":
201
+ error = getattr(event, "error", None)
202
+ raise RuntimeError(getattr(error, "message", None) or "Responses API stream failed")
203
+ except AgentInterrupted:
204
+ raise
205
+ except (asyncio.CancelledError, KeyboardInterrupt) as e:
206
+ raise AgentInterrupted("".join(parts)) from e
207
+ except Exception as e:
208
+ if emitted:
209
+ raise
210
+ raise RetryableResponseError(e) from e
211
+ finally:
212
+ if close := getattr(stream, "close", None):
213
+ with suppress(Exception):
214
+ result = close()
215
+ if asyncio.iscoroutine(result):
216
+ interrupted = isinstance(sys.exc_info()[1], AgentInterrupted)
217
+ closing = asyncio.create_task(result)
218
+ try:
219
+ await asyncio.wait_for(asyncio.shield(closing), timeout=close_timeout)
220
+ except BaseException:
221
+ closing.cancel()
222
+ closing.add_done_callback(_consume_close_result)
223
+ if not interrupted:
224
+ raise
225
+ finish = response_status(response)[0] if response is not None else None
226
+ return ResponseTurn(
227
+ text="".join(parts),
228
+ output=output,
229
+ usage=response_usage(response),
230
+ finish_reason=finish,
231
+ )
232
+
233
+
234
+ def completion_kwargs(
235
+ model: str,
236
+ messages: list[dict[str, Any]],
237
+ provider_id: str | None,
238
+ tools: list[dict[str, Any]] | None = None,
239
+ *,
240
+ vision: bool = True,
241
+ ) -> dict[str, Any]:
242
+ inputs, instructions = request_input(messages, provider_id, vision=vision)
243
+ kwargs: dict[str, Any] = {
244
+ "model": model,
245
+ "input": inputs,
246
+ "tools": response_tools(tools or []),
247
+ "stream": True,
248
+ }
249
+ if instructions is not None:
250
+ kwargs["instructions"] = instructions
251
+ if provider_id == "deepseek" and portable_history(messages, provider_id):
252
+ # DeepSeek rejects thinking-mode replay with portable legacy history.
253
+ kwargs["reasoning"] = {"effort": "none"}
254
+ return kwargs
255
+
256
+
257
+ async def stream_response_with_retries(
258
+ client: AsyncOpenAI,
259
+ kwargs: dict[str, Any],
260
+ *,
261
+ on_delta,
262
+ on_thinking,
263
+ on_answer_to_thinking,
264
+ on_finish,
265
+ retry_sleeps: tuple[float, ...] = RETRY_SLEEPS,
266
+ close_timeout: float = STREAM_CLOSE_TIMEOUT,
267
+ ) -> ResponseTurn:
268
+ """Retry one endpoint without replaying streams that already emitted output."""
269
+
270
+ for attempt in range(len(retry_sleeps) + 1):
271
+ try:
272
+ return await stream_response_once(
273
+ client,
274
+ kwargs,
275
+ on_delta=on_delta,
276
+ on_thinking=on_thinking,
277
+ on_answer_to_thinking=on_answer_to_thinking,
278
+ on_finish=on_finish,
279
+ close_timeout=close_timeout,
280
+ )
281
+ except RetryableResponseError as e:
282
+ if attempt == len(retry_sleeps) or not is_retryable_response_error(e.cause):
283
+ raise
284
+ await asyncio.sleep(retry_sleeps[attempt])
285
+ raise AssertionError("unreachable") # pragma: no cover
286
+
287
+
288
+ async def stream_response_completion(
289
+ client: AsyncOpenAI,
290
+ *,
291
+ model: str,
292
+ messages: list[dict[str, Any]],
293
+ on_delta,
294
+ on_thinking,
295
+ on_answer_to_thinking,
296
+ on_finish=None,
297
+ provider_id: str | None = None,
298
+ tools: list[dict[str, Any]] | None = None,
299
+ vision: bool = True,
300
+ retry_sleeps: tuple[float, ...] = RETRY_SLEEPS,
301
+ close_timeout: float = STREAM_CLOSE_TIMEOUT,
302
+ ) -> ResponseTurn:
303
+ try:
304
+ return await stream_response_with_retries(
305
+ client,
306
+ completion_kwargs(model, messages, provider_id, tools, vision=vision),
307
+ on_delta=on_delta,
308
+ on_thinking=on_thinking,
309
+ on_answer_to_thinking=on_answer_to_thinking,
310
+ on_finish=on_finish,
311
+ retry_sleeps=retry_sleeps,
312
+ close_timeout=close_timeout,
313
+ )
314
+ except RetryableResponseError as e:
315
+ raise e.cause from None
316
+
317
+
318
+ def _default_vision_support(model: str | None) -> bool:
319
+ name = (model or "").lower()
320
+ hints = (
321
+ "text-",
322
+ "embedding",
323
+ "embed",
324
+ "whisper",
325
+ "tts",
326
+ "rerank",
327
+ "bge-",
328
+ "e5-",
329
+ "moderation",
330
+ )
331
+ return not any(hint in name for hint in hints)
332
+
333
+
334
+ class OpenAIResponsesBackend:
335
+ """One OpenAI-compatible Responses endpoint implementing ModelBackend."""
336
+
337
+ def __init__(
338
+ self,
339
+ client: AsyncOpenAI,
340
+ model: str,
341
+ *,
342
+ provider_id: str | None = None,
343
+ context_limit: int | None = None,
344
+ supports_vision: Callable[[str | None], bool] | None = None,
345
+ retry_sleeps: tuple[float, ...] = RETRY_SLEEPS,
346
+ stream_close_timeout: float = STREAM_CLOSE_TIMEOUT,
347
+ ) -> None:
348
+ self.client = client
349
+ self._model = model
350
+ self._provider_id = provider_id
351
+ self._context_limit = context_limit
352
+ self._supports_vision = supports_vision or _default_vision_support
353
+ self.retry_sleeps = retry_sleeps
354
+ self.stream_close_timeout = stream_close_timeout
355
+
356
+ @property
357
+ def model(self) -> str:
358
+ return self._model
359
+
360
+ @property
361
+ def provider_id(self) -> str | None:
362
+ return self._provider_id
363
+
364
+ @property
365
+ def context_limit(self) -> int | None:
366
+ return self._context_limit
367
+
368
+ async def close(self) -> None:
369
+ """Close the endpoint client when this backend is owned by an Agent."""
370
+
371
+ close = getattr(self.client, "close", None)
372
+ if close is not None:
373
+ result = close()
374
+ if inspect.isawaitable(result):
375
+ await result
376
+
377
+ def model_turn(
378
+ self,
379
+ turn: ResponseTurn,
380
+ *,
381
+ provider_id: str | None,
382
+ model: str,
383
+ ) -> ModelTurn:
384
+ calls = []
385
+ for raw in turn.calls:
386
+ call = public_call(raw)
387
+ calls.append(
388
+ ToolCall(
389
+ id=call["id"],
390
+ name=call["function"]["name"],
391
+ arguments=call["function"]["arguments"],
392
+ )
393
+ )
394
+ return ModelTurn(
395
+ text=turn.text,
396
+ calls=calls,
397
+ usage=turn.usage,
398
+ finish_reason=turn.finish_reason,
399
+ model=model,
400
+ state={RAW_ITEMS_KEY: raw_state(provider_id, turn.output)},
401
+ )
402
+
403
+ async def complete(self, request: ModelRequest, events: EventEmitter) -> ModelTurn:
404
+ if request.cancellation is not None:
405
+ request.cancellation.throw_if_cancelled(run_id=request.run_id)
406
+
407
+ async def on_delta(text) -> None:
408
+ await events.emit("text_delta", turn=request.turn, text=text)
409
+
410
+ async def on_thinking(text) -> None:
411
+ await events.emit("reasoning_delta", turn=request.turn, text=text)
412
+
413
+ async def on_answer_to_thinking() -> None:
414
+ await events.emit("answer_to_thinking", turn=request.turn)
415
+
416
+ async def on_finish(reason) -> None:
417
+ await events.emit("model_finished", turn=request.turn, finish_reason=reason)
418
+
419
+ turn = await stream_response_completion(
420
+ self.client,
421
+ model=self._model,
422
+ messages=request.messages,
423
+ on_delta=on_delta,
424
+ on_thinking=on_thinking,
425
+ on_answer_to_thinking=on_answer_to_thinking,
426
+ on_finish=on_finish,
427
+ provider_id=self._provider_id,
428
+ tools=request.tools,
429
+ vision=self._supports_vision(self._model),
430
+ retry_sleeps=self.retry_sleeps,
431
+ close_timeout=self.stream_close_timeout,
432
+ )
433
+ return self.model_turn(turn, provider_id=self._provider_id, model=self._model)
@@ -0,0 +1,141 @@
1
+ """Small plugin SDK with explicit, allowlisted entry-point discovery."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import inspect
6
+ from collections.abc import Iterable
7
+ from dataclasses import dataclass, field
8
+ from importlib import metadata
9
+ from typing import Any, Protocol, runtime_checkable
10
+
11
+ from .backend import BackendRegistry
12
+ from .events import EventBus
13
+ from .lifecycle import LifecycleHooks
14
+ from .tools import ToolRegistry
15
+
16
+ PLUGIN_API_VERSION = 1
17
+ PLUGIN_ENTRY_POINT = "agent0.plugins"
18
+
19
+
20
+ @dataclass
21
+ class PluginContext:
22
+ """Stable registration surface exposed to a plugin during application setup."""
23
+
24
+ tools: ToolRegistry
25
+ backends: BackendRegistry
26
+ events: EventBus
27
+ lifecycle: LifecycleHooks
28
+ services: dict[str, Any] = field(default_factory=dict)
29
+
30
+
31
+ @runtime_checkable
32
+ class Plugin(Protocol):
33
+ api_version: int
34
+
35
+ def register(self, context: PluginContext) -> None: ...
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class PluginInfo:
40
+ """Discovered metadata; creating this object does not import plugin code."""
41
+
42
+ name: str
43
+ value: str
44
+ distribution: str
45
+ entry_point: Any = field(repr=False, compare=False)
46
+
47
+
48
+ class PluginError(RuntimeError):
49
+ pass
50
+
51
+
52
+ def discover_plugins(group: str = PLUGIN_ENTRY_POINT) -> list[PluginInfo]:
53
+ """List installed plugins without importing them."""
54
+
55
+ try:
56
+ points = metadata.entry_points().select(group=group)
57
+ except AttributeError: # Python 3.10's older EntryPoints API
58
+ points = metadata.entry_points().get(group, ())
59
+ found = [
60
+ PluginInfo(
61
+ name=point.name,
62
+ value=point.value,
63
+ distribution=getattr(getattr(point, "dist", None), "name", "") or "",
64
+ entry_point=point,
65
+ )
66
+ for point in points
67
+ ]
68
+ return sorted(found, key=lambda item: (item.name, item.distribution, item.value))
69
+
70
+
71
+ class PluginManager:
72
+ """Load trusted plugin objects and optional explicitly named entry points."""
73
+
74
+ def __init__(self, context: PluginContext, *, group: str = PLUGIN_ENTRY_POINT) -> None:
75
+ self.context = context
76
+ self.group = group
77
+ self._loaded: dict[str, Plugin] = {}
78
+ self._order: list[str] = []
79
+
80
+ @property
81
+ def loaded(self) -> tuple[str, ...]:
82
+ return tuple(self._order)
83
+
84
+ def discover(self) -> list[PluginInfo]:
85
+ return discover_plugins(self.group)
86
+
87
+ def load(self, plugin: Plugin, *, name: str = "") -> str:
88
+ plugin_name = name or str(
89
+ getattr(plugin, "name", "") or f"{type(plugin).__module__}.{type(plugin).__qualname__}"
90
+ )
91
+ if plugin_name in self._loaded:
92
+ raise PluginError(f"plugin already loaded: {plugin_name}")
93
+ version = getattr(plugin, "api_version", None)
94
+ if version != PLUGIN_API_VERSION:
95
+ raise PluginError(
96
+ f"plugin {plugin_name} uses API {version!r}; expected {PLUGIN_API_VERSION}"
97
+ )
98
+ register = getattr(plugin, "register", None)
99
+ if not callable(register):
100
+ raise PluginError(f"plugin {plugin_name} has no register(context) method")
101
+ try:
102
+ register(self.context)
103
+ except Exception as error:
104
+ raise PluginError(f"plugin {plugin_name} failed to register: {error}") from error
105
+ self._loaded[plugin_name] = plugin
106
+ self._order.append(plugin_name)
107
+ return plugin_name
108
+
109
+ def load_discovered(self, enabled: Iterable[str]) -> tuple[str, ...]:
110
+ """Import only the explicitly allowlisted discovered plugin names."""
111
+
112
+ discovered: dict[str, PluginInfo] = {}
113
+ for info in self.discover():
114
+ if info.name in discovered:
115
+ raise PluginError(f"multiple installed plugins named {info.name}")
116
+ discovered[info.name] = info
117
+ loaded = []
118
+ for name in enabled:
119
+ info = discovered.get(name)
120
+ if info is None:
121
+ raise PluginError(f"enabled plugin is not installed: {name}")
122
+ try:
123
+ plugin = info.entry_point.load()
124
+ except Exception as error:
125
+ raise PluginError(f"cannot import plugin {name}: {error}") from error
126
+ if isinstance(plugin, type):
127
+ plugin = plugin()
128
+ loaded.append(self.load(plugin, name=name))
129
+ return tuple(loaded)
130
+
131
+ async def close(self) -> None:
132
+ """Close plugins in reverse registration order when they provide close()."""
133
+
134
+ for name in reversed(self._order):
135
+ plugin = self._loaded[name]
136
+ close = getattr(plugin, "close", None)
137
+ if close is None:
138
+ continue
139
+ result = close()
140
+ if inspect.isawaitable(result):
141
+ await result
@@ -0,0 +1,95 @@
1
+ """Provider-neutral model provider metadata and API-key resolution."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from dataclasses import dataclass
7
+
8
+ from .client import make_openai_client
9
+
10
+
11
+ @dataclass(frozen=True)
12
+ class Credential:
13
+ api_key: str
14
+ base_url: str
15
+ source: str
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class ProviderSpec:
20
+ """Static metadata for an OpenAI-compatible API provider."""
21
+
22
+ id: str
23
+ aliases: tuple[str, ...]
24
+ env_keys: tuple[str, ...]
25
+ base_url: str
26
+ prompt: str
27
+ default_model: str = ""
28
+ login_name: str = ""
29
+
30
+ @property
31
+ def preferred_login(self) -> str:
32
+ return self.login_name or self.id
33
+
34
+ def resolve_env(self) -> Credential | None:
35
+ for env in self.env_keys:
36
+ if key := os.environ.get(env, "").strip():
37
+ return Credential(key, self.base_url, "env")
38
+ return None
39
+
40
+ def resolve(self) -> Credential | None:
41
+ """Resolve the default environment credential; managed hosts may override."""
42
+
43
+ return self.resolve_env()
44
+
45
+ def make_client(self, credential: Credential):
46
+ """Create a default runtime client; managed hosts may override this."""
47
+
48
+ return make_openai_client(credential.api_key, credential.base_url)
49
+
50
+
51
+ BUILTIN_PROVIDERS = (
52
+ ProviderSpec(
53
+ "deepseek",
54
+ ("ds",),
55
+ ("DEEPSEEK_API_KEY",),
56
+ "https://api.deepseek.com",
57
+ "DeepSeek API key",
58
+ "deepseek-chat",
59
+ ),
60
+ ProviderSpec(
61
+ "kimi",
62
+ (),
63
+ ("KIMI_API_KEY",),
64
+ "https://api.kimi.com/coding/v1",
65
+ "Kimi Code API key",
66
+ "kimi-for-coding",
67
+ ),
68
+ )
69
+
70
+ _REGISTRY: dict[str, ProviderSpec] = {}
71
+ for _provider in BUILTIN_PROVIDERS:
72
+ _REGISTRY[_provider.id] = _provider
73
+ for _alias in _provider.aliases:
74
+ _REGISTRY[_alias] = _provider
75
+
76
+
77
+ def get_provider(name: str) -> ProviderSpec | None:
78
+ return _REGISTRY.get(name.lower().replace("_", "-"))
79
+
80
+
81
+ def list_providers() -> list[ProviderSpec]:
82
+ return list(BUILTIN_PROVIDERS)
83
+
84
+
85
+ def default_model_for(provider_id: str | None) -> str:
86
+ """Fallback model when a provider's /models list is unavailable."""
87
+
88
+ provider = get_provider(provider_id or "")
89
+ if provider and provider.default_model:
90
+ return provider.default_model
91
+ return BUILTIN_PROVIDERS[0].default_model
92
+
93
+
94
+ def resolve_all_env() -> dict[str, Credential]:
95
+ return {p.id: c for p in BUILTIN_PROVIDERS if (c := p.resolve_env())}
File without changes