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,267 @@
1
+ """OpenAI Responses protocol helpers.
2
+
3
+ The session stores ordinary conversation/tool messages. Provider-specific output
4
+ items live in assistant messages' private ``_responses`` state: they are required
5
+ by some Responses implementations on the next request, but are never presented
6
+ as chat messages to the UI or to another provider.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass, field
12
+ from typing import Any
13
+
14
+ RAW_ITEMS_KEY = "_responses"
15
+ IMAGES_KEY = "_images" # tool-result image blocks: [{"data": base64, "mimeType": ...}]
16
+
17
+
18
+ @dataclass
19
+ class ResponseTurn:
20
+ """One completed model round, independent of the provider SDK's types."""
21
+
22
+ text: str = ""
23
+ output: list[dict[str, Any]] = field(default_factory=list)
24
+ usage: dict[str, int] | None = None
25
+ finish_reason: str | None = None
26
+
27
+ @property
28
+ def calls(self) -> list[dict[str, Any]]:
29
+ return [item for item in self.output if item.get("type") == "function_call"]
30
+
31
+
32
+ def plain_item(value: Any) -> dict[str, Any]:
33
+ """Convert an SDK output item/event to a JSON-safe dict, dropping nulls."""
34
+ if isinstance(value, dict):
35
+ data = value
36
+ elif hasattr(value, "model_dump"):
37
+ data = value.model_dump()
38
+ elif hasattr(value, "__dict__"):
39
+ data = vars(value)
40
+ else:
41
+ data = dict(value)
42
+ return {k: plain_value(v) for k, v in data.items() if v is not None}
43
+
44
+
45
+ def plain_value(value: Any) -> Any:
46
+ if isinstance(value, dict):
47
+ return {k: plain_value(v) for k, v in value.items() if v is not None}
48
+ if isinstance(value, (list, tuple)):
49
+ return [plain_value(v) for v in value]
50
+ if hasattr(value, "model_dump"):
51
+ return plain_value(value.model_dump())
52
+ return value
53
+
54
+
55
+ def raw_output(message: dict[str, Any], provider_id: str | None) -> list[dict[str, Any]] | None:
56
+ """Return raw items only on the provider that produced them."""
57
+ state = message.get(RAW_ITEMS_KEY)
58
+ if not isinstance(state, dict) or state.get("provider") != provider_id:
59
+ return None
60
+ items = state.get("items")
61
+ if not isinstance(items, list) or not all(isinstance(item, dict) for item in items):
62
+ return None
63
+ return items or None
64
+
65
+
66
+ def request_input(
67
+ messages: list[dict[str, Any]],
68
+ provider_id: str | None = None,
69
+ *,
70
+ vision: bool = True,
71
+ ) -> tuple[list[dict[str, Any]], str | None]:
72
+ """Project chat-shaped history to Responses input and optional instructions.
73
+
74
+ Raw output items replace their assistant message only for the provider that
75
+ produced them. This keeps compaction and provider switching stateless.
76
+ """
77
+ instructions = None
78
+ out: list[dict[str, Any]] = []
79
+ for message in messages:
80
+ role = message.get("role")
81
+ if role == "system":
82
+ instructions = message.get("content") or None
83
+ elif role in ("user", "assistant"):
84
+ raw = raw_output(message, provider_id) if role == "assistant" else None
85
+ if raw is not None:
86
+ out.extend(raw)
87
+ continue
88
+ out.append({"role": role, "content": message.get("content") or ""})
89
+ for call in message.get("tool_calls") or []:
90
+ out.append(legacy_function_call(call))
91
+ elif role == "tool":
92
+ out.append(
93
+ {
94
+ "type": "function_call_output",
95
+ "call_id": message.get("tool_call_id", ""),
96
+ "output": tool_output(message, vision=vision),
97
+ }
98
+ )
99
+ return out, instructions
100
+
101
+
102
+ def tool_output(message: dict[str, Any], *, vision: bool = True) -> str | list[dict[str, Any]]:
103
+ """Tool text plus inline images, as Responses function_call_output content.
104
+
105
+ Text-only models get the text alone: pi drops images the same way instead
106
+ of letting the provider reject the whole request.
107
+ """
108
+ text = message.get("content") or ""
109
+ blocks = (message.get(IMAGES_KEY) or message.get("_attachments")) if vision else None
110
+ if not isinstance(blocks, list) or not blocks:
111
+ return text
112
+ parts: list[dict[str, Any]] = [{"type": "input_text", "text": text}]
113
+ for block in blocks:
114
+ if not isinstance(block, dict):
115
+ continue
116
+ data = block.get("data")
117
+ mime = block.get("mimeType") or block.get("mime_type") or "image/png"
118
+ if isinstance(data, str) and data:
119
+ parts.append({"type": "input_image", "image_url": f"data:{mime};base64,{data}"})
120
+ return parts if len(parts) > 1 else text
121
+
122
+
123
+ def legacy_function_call(call: dict[str, Any]) -> dict[str, Any]:
124
+ """Read a version-1 snapshot without inventing unavailable reasoning state."""
125
+ function = call.get("function") or {}
126
+ return {
127
+ "type": "function_call",
128
+ "call_id": call.get("id", ""),
129
+ "name": function.get("name", ""),
130
+ "arguments": function.get("arguments") or "{}",
131
+ }
132
+
133
+
134
+ def portable_history(messages: list[dict[str, Any]], provider_id: str | None) -> bool:
135
+ """Whether history contains assistant output without this provider's raw items.
136
+
137
+ DeepSeek rejects thinking-mode requests containing old assistant turns whose
138
+ reasoning is unavailable (legacy snapshots, compaction, provider switches).
139
+ """
140
+ return any(
141
+ message.get("role") == "assistant" and raw_output(message, provider_id) is None
142
+ for message in messages
143
+ )
144
+
145
+
146
+ def discard_raw_output(messages: list[dict[str, Any]]) -> None:
147
+ """Use portable text after compaction makes raw output items stale."""
148
+ for message in messages:
149
+ message.pop(RAW_ITEMS_KEY, None)
150
+
151
+
152
+ def response_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
153
+ """Chat function definitions have one extra ``function`` wrapper."""
154
+ converted = []
155
+ for tool in tools:
156
+ function = tool.get("function") or {}
157
+ converted.append(
158
+ {
159
+ "type": "function",
160
+ "name": function.get("name", ""),
161
+ "description": function.get("description", ""),
162
+ "parameters": function.get("parameters") or {"type": "object", "properties": {}},
163
+ }
164
+ )
165
+ return converted
166
+
167
+
168
+ def _first_int(get: Any, *keys: str) -> int | None:
169
+ for key in keys:
170
+ value = get(key)
171
+ if value is not None:
172
+ return int(value)
173
+ return None
174
+
175
+
176
+ def response_usage(response: Any) -> dict[str, int] | None:
177
+ """Map Responses or Chat Completions usage onto the UI's token names.
178
+
179
+ Responses reports input_tokens/output_tokens. Some compatible endpoints
180
+ still report prompt_tokens/completion_tokens. Prefer the Responses names.
181
+ """
182
+ usage = getattr(response, "usage", None)
183
+ if usage is None and isinstance(response, dict):
184
+ usage = response.get("usage")
185
+ if usage is None:
186
+ return None
187
+ get = (
188
+ usage.get
189
+ if isinstance(usage, dict)
190
+ else (lambda key, default=None: getattr(usage, key, default))
191
+ )
192
+ prompt = _first_int(get, "input_tokens", "prompt_tokens")
193
+ completion = _first_int(get, "output_tokens", "completion_tokens")
194
+ total = _first_int(get, "total_tokens")
195
+ if total is None and prompt is not None and completion is not None:
196
+ total = prompt + completion
197
+ out = {
198
+ key: value
199
+ for key, value in (
200
+ ("prompt_tokens", prompt),
201
+ ("completion_tokens", completion),
202
+ ("total_tokens", total),
203
+ )
204
+ if value is not None
205
+ }
206
+ return out or None
207
+
208
+
209
+ def response_status(response: Any) -> tuple[str | None, str | None]:
210
+ """Return (UI finish reason, incomplete reason).
211
+
212
+ Responses reports status/incomplete_details. Compatible endpoints may still
213
+ report Chat Completions finish_reason. Known cases become stop/length so
214
+ the truncation notice does not depend on which name arrived.
215
+ """
216
+ get = (
217
+ response.get
218
+ if isinstance(response, dict)
219
+ else (lambda key, default=None: getattr(response, key, default))
220
+ )
221
+ status = get("status")
222
+ details = get("incomplete_details") or {}
223
+ reason = (
224
+ details.get("reason") if isinstance(details, dict) else getattr(details, "reason", None)
225
+ )
226
+ finish = get("finish_reason")
227
+ if reason == "max_output_tokens" or finish == "length":
228
+ return "length", reason
229
+ if status == "completed" or finish == "stop":
230
+ return "stop", reason
231
+ if isinstance(finish, str) and finish:
232
+ return finish, reason
233
+ return status if isinstance(status, str) else None, reason
234
+
235
+
236
+ def output_text(items: list[dict[str, Any]]) -> str:
237
+ """Fallback for providers that send output items without text deltas."""
238
+ parts = []
239
+ for item in items:
240
+ if item.get("type") != "message":
241
+ continue
242
+ for part in item.get("content") or []:
243
+ if part.get("type") == "output_text" and isinstance(part.get("text"), str):
244
+ parts.append(part["text"])
245
+ return "".join(parts)
246
+
247
+
248
+ def reasoning_text(item: dict[str, Any]) -> str:
249
+ parts = [part.get("text", "") for part in item.get("content") or []]
250
+ parts += [part.get("text", "") for part in item.get("summary") or []]
251
+ return "".join(part for part in parts if isinstance(part, str))
252
+
253
+
254
+ def public_call(call: dict[str, Any]) -> dict[str, Any]:
255
+ """Project a Responses function call to the existing agent loop's shape."""
256
+ return {
257
+ "id": call.get("call_id") or call.get("id") or "",
258
+ "type": "function",
259
+ "function": {
260
+ "name": call.get("name") or "",
261
+ "arguments": call.get("arguments") or "{}",
262
+ },
263
+ }
264
+
265
+
266
+ def raw_state(provider_id: str | None, items: list[dict[str, Any]]) -> dict[str, Any]:
267
+ return {"provider": provider_id, "items": items}
@@ -0,0 +1,335 @@
1
+ """Zero-config intent routing over the runtime's reviewed model capabilities."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import json
7
+ import math
8
+ from collections.abc import Iterable
9
+ from contextlib import suppress
10
+ from dataclasses import dataclass, field
11
+ from typing import Any, Callable
12
+
13
+ from openai import AsyncOpenAI
14
+
15
+ from agent0_runtime.capabilities import MODEL_CAPABILITIES, ModelCapability
16
+
17
+ from .providers import Credential, ProviderSpec, list_providers
18
+ from .responses import IMAGES_KEY, output_text, plain_item
19
+
20
+ AUTO_REF = "auto"
21
+ SCORE_TIMEOUT = 5.0
22
+ SCORE_MAX_TOKENS = 500
23
+ SWITCH_SCORE_MARGIN = 3.0
24
+ _INTENTS = frozenset({"quick", "coding", "debugging", "reasoning"})
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class RouteTarget:
29
+ """One concrete upstream request destination."""
30
+
31
+ provider_id: str
32
+ model: str
33
+ credential: Credential
34
+ client: AsyncOpenAI
35
+ context_limit: int | None = None
36
+ capability: ModelCapability | None = None
37
+
38
+ @property
39
+ def ref(self) -> str:
40
+ return f"{self.provider_id}/{self.model}"
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class RouteSelection:
45
+ intent: str
46
+ scores: dict[str, float]
47
+ scorer_ref: str
48
+ error: str = ""
49
+
50
+
51
+ @dataclass
52
+ class FailoverRoute:
53
+ """Select once per user task, then keep that order through tool rounds."""
54
+
55
+ targets: tuple[RouteTarget, ...]
56
+ intent_routing: bool = False
57
+ index: int = 0
58
+ selection: RouteSelection | None = field(init=False, default=None)
59
+ _active: tuple[RouteTarget, ...] = field(init=False, repr=False)
60
+ _started: bool = field(init=False, default=False, repr=False)
61
+
62
+ def __post_init__(self) -> None:
63
+ if not self.targets:
64
+ raise ValueError("auto: a route needs at least one target")
65
+ self._active = self.targets
66
+
67
+ @property
68
+ def current(self) -> RouteTarget:
69
+ return self._active[self.index]
70
+
71
+ @property
72
+ def active_targets(self) -> tuple[RouteTarget, ...]:
73
+ return self._active[self.index :]
74
+
75
+ def advance(self) -> RouteTarget | None:
76
+ """Move to the next target, or return None after the last one."""
77
+ if self.index + 1 >= len(self._active):
78
+ return None
79
+ self.index += 1
80
+ return self.current
81
+
82
+ async def start(
83
+ self,
84
+ task: str,
85
+ messages: list[dict[str, Any]],
86
+ estimated_tokens: int,
87
+ ) -> None:
88
+ """Choose a new task's order; execution failover never invokes the scorer."""
89
+ # A new route has no incumbent: its first task must use the argmax.
90
+ previous = self.current if self._started else None
91
+ self._started = True
92
+ self.index = 0
93
+ self.selection = None
94
+ self._active = self.targets
95
+ if not self.intent_routing:
96
+ return
97
+ eligible = _context_eligible(self.targets, estimated_tokens)
98
+ self._active = eligible
99
+ if len(eligible) == 1:
100
+ return
101
+ # A task carrying images can only run on models that accept them, so a
102
+ # text-only candidate must never be scored, selected, or failed over to.
103
+ images = _has_images(messages)
104
+ if images:
105
+ eligible = _vision_eligible(eligible)
106
+ self._active = eligible
107
+ if len(eligible) == 1:
108
+ return
109
+ scorer = _scorer_for(eligible, previous)
110
+ try:
111
+ intent, scores = await _score_targets(
112
+ scorer,
113
+ eligible,
114
+ task,
115
+ messages,
116
+ has_images=images,
117
+ )
118
+ except Exception as e: # scoring is an optimization, never a task SPOF
119
+ self._active = _fallback_order(eligible, previous)
120
+ self.selection = RouteSelection("default", {}, scorer.ref, type(e).__name__)
121
+ return
122
+ self._active = _scored_order(eligible, previous, scores)
123
+ self.selection = RouteSelection(intent, scores, scorer.ref)
124
+
125
+ async def close(self) -> None:
126
+ seen: set[int] = set()
127
+ for target in self.targets:
128
+ client: Any = target.client
129
+ if id(client) in seen:
130
+ continue
131
+ seen.add(id(client))
132
+ with suppress(Exception):
133
+ result = client.close()
134
+ if asyncio.iscoroutine(result):
135
+ await result
136
+
137
+
138
+ def build_auto_route(
139
+ credentials: dict[str, Credential],
140
+ *,
141
+ models: list[str] | None = None,
142
+ context_limit: Callable[[str], int | None] | None = None,
143
+ provider_specs: Iterable[ProviderSpec] | None = None,
144
+ ) -> FailoverRoute:
145
+ """Build auto from reviewed models with optional host-managed providers."""
146
+
147
+ available = list_providers() if provider_specs is None else provider_specs
148
+ providers = {p.id: p for p in available}
149
+ listed = {ref.lower() for ref in models or []}
150
+ targets: list[RouteTarget] = []
151
+ for capability in MODEL_CAPABILITIES:
152
+ if not capability.supports_responses or not capability.supports_tools:
153
+ continue
154
+ if listed and capability.ref.lower() not in listed:
155
+ continue
156
+ provider = providers.get(capability.provider_id)
157
+ if provider is None:
158
+ continue
159
+ credential = credentials.get(provider.id) or provider.resolve()
160
+ if credential is None:
161
+ continue
162
+ targets.append(
163
+ RouteTarget(
164
+ provider_id=provider.id,
165
+ model=capability.model,
166
+ credential=credential,
167
+ client=provider.make_client(credential),
168
+ context_limit=(
169
+ context_limit(capability.model) if context_limit else capability.context_limit
170
+ ),
171
+ capability=capability,
172
+ )
173
+ )
174
+ if not targets:
175
+ raise ValueError("auto: no supported models with credentials")
176
+ return FailoverRoute(tuple(targets), intent_routing=True)
177
+
178
+
179
+ def _has_images(messages: list[dict[str, Any]]) -> bool:
180
+ """Whether this conversation already carries inline images for the model."""
181
+ return any(message.get(IMAGES_KEY) or message.get("_attachments") for message in messages)
182
+
183
+
184
+ def _vision_eligible(targets: tuple[RouteTarget, ...]) -> tuple[RouteTarget, ...]:
185
+ """Drop candidates that would silently lose the images the task depends on."""
186
+ seeing = tuple(
187
+ target
188
+ for target in targets
189
+ if target.capability is None or target.capability.supports_vision
190
+ )
191
+ return seeing or targets
192
+
193
+
194
+ def _context_eligible(
195
+ targets: tuple[RouteTarget, ...],
196
+ estimated_tokens: int,
197
+ ) -> tuple[RouteTarget, ...]:
198
+ fitting = tuple(
199
+ target
200
+ for target in targets
201
+ if target.context_limit is None or estimated_tokens < target.context_limit
202
+ )
203
+ if fitting:
204
+ return fitting
205
+ # Nothing fits as-is: pick the largest window and let normal compaction run.
206
+ return (max(targets, key=lambda target: target.context_limit or 0),)
207
+
208
+
209
+ def _scorer_for(
210
+ targets: tuple[RouteTarget, ...],
211
+ previous: RouteTarget | None,
212
+ ) -> RouteTarget:
213
+ scorers = [
214
+ target for target in targets if target.capability and target.capability.scorer_priority
215
+ ]
216
+ if scorers:
217
+ return min(scorers, key=lambda target: target.capability.scorer_priority or 99)
218
+ return previous if previous in targets else targets[0]
219
+
220
+
221
+ def _fallback_order(
222
+ targets: tuple[RouteTarget, ...],
223
+ previous: RouteTarget | None,
224
+ ) -> tuple[RouteTarget, ...]:
225
+ if previous not in targets:
226
+ return targets
227
+ return (previous, *(target for target in targets if target is not previous))
228
+
229
+
230
+ def _scored_order(
231
+ targets: tuple[RouteTarget, ...],
232
+ previous: RouteTarget | None,
233
+ scores: dict[str, float],
234
+ ) -> tuple[RouteTarget, ...]:
235
+ ordered = sorted(targets, key=lambda target: -scores.get(target.ref, -1.0))
236
+ if previous in targets and previous.ref in scores:
237
+ best_score = scores.get(ordered[0].ref, -1.0)
238
+ if best_score - scores[previous.ref] < SWITCH_SCORE_MARGIN:
239
+ ordered = [previous, *(target for target in ordered if target is not previous)]
240
+ return tuple(ordered)
241
+
242
+
243
+ def _recent_context(messages: list[dict[str, Any]]) -> str:
244
+ entries: list[str] = []
245
+ for message in messages[:-1]:
246
+ role = message.get("role")
247
+ content = message.get("content")
248
+ if role in ("user", "assistant") and isinstance(content, str) and content.strip():
249
+ entries.append(f"{role}: {content.strip()[:2000]}")
250
+ return "\n".join(entries[-2:])[:4000]
251
+
252
+
253
+ async def _score_targets(
254
+ scorer: RouteTarget,
255
+ targets: tuple[RouteTarget, ...],
256
+ task: str,
257
+ messages: list[dict[str, Any]],
258
+ *,
259
+ has_images: bool = False,
260
+ ) -> tuple[str, dict[str, float]]:
261
+ candidates = [
262
+ {
263
+ "ref": target.ref,
264
+ "strengths": sorted(target.capability.strengths) if target.capability else [],
265
+ "routing_hint": target.capability.routing_hint if target.capability else "",
266
+ "context_limit": target.context_limit,
267
+ "sees_images": (target.capability.supports_vision if target.capability else True),
268
+ }
269
+ for target in targets
270
+ ]
271
+ payload = {
272
+ "task": task[:6000],
273
+ "recent_context": _recent_context(messages),
274
+ "candidates": candidates,
275
+ }
276
+ if has_images:
277
+ # Metadata only: the scorer never receives image bytes, just the fact that
278
+ # the task includes attachments it cannot see.
279
+ payload["has_images"] = True
280
+ instructions = (
281
+ "You are a model router, not the task solver. Score every supplied candidate "
282
+ "from 0 to 100 for this task. Use fast/coding models for simple or quick coding "
283
+ "tasks and strong models for difficult debugging, architecture, and reasoning. "
284
+ "Classify quick as explanations or trivial edits, coding as implementation or tests, "
285
+ "debugging as failures or root causes, and reasoning as design, architecture, "
286
+ "tradeoffs, or proofs. Candidate order is not a ranking; use routing_hint to "
287
+ "differentiate models within a tier. Consider tool use and context needs. "
288
+ "When has_images is true the task includes image attachments you cannot see; "
289
+ "prefer candidates whose sees_images is true. "
290
+ "Return only one JSON object with this shape: "
291
+ '{"intent":"quick|coding|debugging|reasoning","scores":{"provider/model":0}}. '
292
+ "Use only the exact candidate refs; do not answer the task."
293
+ )
294
+ kwargs: dict[str, Any] = {
295
+ "model": scorer.model,
296
+ "instructions": instructions,
297
+ "input": json.dumps(payload, ensure_ascii=False),
298
+ "stream": False,
299
+ "temperature": 0,
300
+ "max_output_tokens": SCORE_MAX_TOKENS,
301
+ }
302
+ if scorer.provider_id == "deepseek":
303
+ kwargs["reasoning"] = {"effort": "none"}
304
+ response = await asyncio.wait_for(
305
+ scorer.client.responses.create(**kwargs), timeout=SCORE_TIMEOUT
306
+ )
307
+ output = (
308
+ response.get("output") if isinstance(response, dict) else getattr(response, "output", [])
309
+ )
310
+ text = output_text([plain_item(item) for item in output or []])
311
+ return _parse_scores(text, targets)
312
+
313
+
314
+ def _parse_scores(text: str, targets: tuple[RouteTarget, ...]) -> tuple[str, dict[str, float]]:
315
+ raw = text.strip()
316
+ if raw.startswith("```") and raw.endswith("```") and "\n" in raw:
317
+ raw = raw.split("\n", 1)[1].rsplit("\n", 1)[0].strip()
318
+ data = json.loads(raw)
319
+ if not isinstance(data, dict) or not isinstance(data.get("scores"), dict):
320
+ raise ValueError("auto: scorer returned no scores")
321
+ intent = data.get("intent")
322
+ if intent not in _INTENTS:
323
+ intent = "coding"
324
+ refs = {target.ref.lower(): target.ref for target in targets}
325
+ scores: dict[str, float] = {}
326
+ for ref, value in data["scores"].items():
327
+ canonical = refs.get(str(ref).lower())
328
+ if canonical is None or isinstance(value, bool) or not isinstance(value, (int, float)):
329
+ continue
330
+ score = float(value)
331
+ if math.isfinite(score) and 0 <= score <= 100:
332
+ scores[canonical] = score
333
+ if not scores:
334
+ raise ValueError("auto: scorer returned no usable scores")
335
+ return intent, scores