submilli 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.
- submilli/__init__.py +95 -0
- submilli/_async_client.py +303 -0
- submilli/_base.py +282 -0
- submilli/_client.py +292 -0
- submilli/_errors.py +207 -0
- submilli/_types.py +254 -0
- submilli/_version.py +6 -0
- submilli/py.typed +0 -0
- submilli/schema.py +35 -0
- submilli-0.1.0.dist-info/METADATA +228 -0
- submilli-0.1.0.dist-info/RECORD +13 -0
- submilli-0.1.0.dist-info/WHEEL +4 -0
- submilli-0.1.0.dist-info/licenses/LICENSE +201 -0
submilli/__init__.py
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""The Python SDK for submilli-server's HTTP API.
|
|
2
|
+
|
|
3
|
+
```python
|
|
4
|
+
from submilli import AsyncSubmilli
|
|
5
|
+
|
|
6
|
+
async with AsyncSubmilli() as client:
|
|
7
|
+
session = await client.sessions.create("research", variables={"userId": "u_ada"})
|
|
8
|
+
result = await client.sessions.run(session.id, code, idempotency_key="call-1")
|
|
9
|
+
```
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from submilli._async_client import AsyncBlueprints, AsyncRuns, AsyncSessions, AsyncSubmilli, AsyncToolHandler
|
|
13
|
+
from submilli._base import DEFAULT_BASE_URL, idempotency_key
|
|
14
|
+
from submilli._client import Blueprints, Runs, Sessions, Submilli, ToolHandler
|
|
15
|
+
from submilli._errors import (
|
|
16
|
+
APIConnectionError,
|
|
17
|
+
APIStatusError,
|
|
18
|
+
APITimeoutError,
|
|
19
|
+
AuthenticationError,
|
|
20
|
+
BadRequestError,
|
|
21
|
+
ConflictError,
|
|
22
|
+
ForbiddenError,
|
|
23
|
+
IdempotencyError,
|
|
24
|
+
InternalServerError,
|
|
25
|
+
NotFoundError,
|
|
26
|
+
RunNotSuspendedError,
|
|
27
|
+
ServiceUnavailableError,
|
|
28
|
+
SessionRequiresSecretsError,
|
|
29
|
+
SubmilliError,
|
|
30
|
+
UnknownBlueprintError,
|
|
31
|
+
UnknownCallError,
|
|
32
|
+
UnknownRunError,
|
|
33
|
+
UnknownSessionError,
|
|
34
|
+
)
|
|
35
|
+
from submilli._types import (
|
|
36
|
+
BlueprintPrompt,
|
|
37
|
+
CreatedSession,
|
|
38
|
+
ExecuteResult,
|
|
39
|
+
LastRun,
|
|
40
|
+
PackageDocs,
|
|
41
|
+
PendingCall,
|
|
42
|
+
RunError,
|
|
43
|
+
RunningRun,
|
|
44
|
+
RunState,
|
|
45
|
+
SuspendedRun,
|
|
46
|
+
ToolDeclaration,
|
|
47
|
+
ToolResult,
|
|
48
|
+
)
|
|
49
|
+
from submilli._version import __version__
|
|
50
|
+
|
|
51
|
+
__all__ = [
|
|
52
|
+
"DEFAULT_BASE_URL",
|
|
53
|
+
"APIConnectionError",
|
|
54
|
+
"APIStatusError",
|
|
55
|
+
"APITimeoutError",
|
|
56
|
+
"AsyncBlueprints",
|
|
57
|
+
"AsyncRuns",
|
|
58
|
+
"AsyncSessions",
|
|
59
|
+
"AsyncSubmilli",
|
|
60
|
+
"AsyncToolHandler",
|
|
61
|
+
"AuthenticationError",
|
|
62
|
+
"BadRequestError",
|
|
63
|
+
"BlueprintPrompt",
|
|
64
|
+
"Blueprints",
|
|
65
|
+
"ConflictError",
|
|
66
|
+
"CreatedSession",
|
|
67
|
+
"ExecuteResult",
|
|
68
|
+
"ForbiddenError",
|
|
69
|
+
"IdempotencyError",
|
|
70
|
+
"InternalServerError",
|
|
71
|
+
"LastRun",
|
|
72
|
+
"NotFoundError",
|
|
73
|
+
"PackageDocs",
|
|
74
|
+
"PendingCall",
|
|
75
|
+
"RunError",
|
|
76
|
+
"RunNotSuspendedError",
|
|
77
|
+
"RunState",
|
|
78
|
+
"RunningRun",
|
|
79
|
+
"Runs",
|
|
80
|
+
"ServiceUnavailableError",
|
|
81
|
+
"SessionRequiresSecretsError",
|
|
82
|
+
"Sessions",
|
|
83
|
+
"Submilli",
|
|
84
|
+
"SubmilliError",
|
|
85
|
+
"SuspendedRun",
|
|
86
|
+
"ToolDeclaration",
|
|
87
|
+
"ToolHandler",
|
|
88
|
+
"ToolResult",
|
|
89
|
+
"UnknownBlueprintError",
|
|
90
|
+
"UnknownCallError",
|
|
91
|
+
"UnknownRunError",
|
|
92
|
+
"UnknownSessionError",
|
|
93
|
+
"__version__",
|
|
94
|
+
"idempotency_key",
|
|
95
|
+
]
|
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
"""`AsyncSubmilli`: the HTTP API of one submilli-server, for asyncio."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import inspect
|
|
7
|
+
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
|
8
|
+
from types import TracebackType
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
import httpx
|
|
12
|
+
|
|
13
|
+
from submilli import _base as b
|
|
14
|
+
from submilli._errors import (
|
|
15
|
+
APIConnectionError,
|
|
16
|
+
APITimeoutError,
|
|
17
|
+
RunNotSuspendedError,
|
|
18
|
+
SubmilliError,
|
|
19
|
+
UnknownCallError,
|
|
20
|
+
)
|
|
21
|
+
from submilli._types import (
|
|
22
|
+
BlueprintPrompt,
|
|
23
|
+
CreatedSession,
|
|
24
|
+
ExecuteResult,
|
|
25
|
+
LastRun,
|
|
26
|
+
PackageDocs,
|
|
27
|
+
PendingCall,
|
|
28
|
+
RunningRun,
|
|
29
|
+
RunState,
|
|
30
|
+
ToolDeclaration,
|
|
31
|
+
ToolResult,
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
AsyncToolHandler = Callable[[PendingCall], "ToolResult | Awaitable[ToolResult]"]
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class AsyncSubmilli:
|
|
38
|
+
"""The HTTP API of one submilli-server, for one API token.
|
|
39
|
+
|
|
40
|
+
Args:
|
|
41
|
+
base_url: The server. Defaults to `$SUBMILLI_SERVER`, then `http://127.0.0.1:8128`.
|
|
42
|
+
token: API token. Defaults to `$SUBMILLI_SERVER_TOKEN`. A server started
|
|
43
|
+
with `--allow-unauthenticated` needs none.
|
|
44
|
+
timeout: Seconds per request, or an `httpx.Timeout`.
|
|
45
|
+
max_retries: Further attempts after a connection failure or a 502, 503
|
|
46
|
+
or 504, for requests that are safe to repeat: reads, deletes,
|
|
47
|
+
rebinds, resumes, and executes with an idempotency key.
|
|
48
|
+
http_client: An `httpx.AsyncClient` to send with. Its lifetime is yours.
|
|
49
|
+
Without one, the client keeps one per event loop and closes it in
|
|
50
|
+
`aclose`.
|
|
51
|
+
|
|
52
|
+
Example:
|
|
53
|
+
```python
|
|
54
|
+
async with AsyncSubmilli() as client:
|
|
55
|
+
session = await client.sessions.create("research", variables={"userId": "u_ada"})
|
|
56
|
+
result = await client.sessions.run(session.id, code, idempotency_key="call-1")
|
|
57
|
+
```
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
def __init__(
|
|
61
|
+
self,
|
|
62
|
+
*,
|
|
63
|
+
base_url: str | None = None,
|
|
64
|
+
token: str | None = None,
|
|
65
|
+
timeout: float | httpx.Timeout = b.DEFAULT_TIMEOUT,
|
|
66
|
+
max_retries: int = b.DEFAULT_MAX_RETRIES,
|
|
67
|
+
http_client: httpx.AsyncClient | None = None,
|
|
68
|
+
) -> None:
|
|
69
|
+
self._settings = b.Settings.resolve(base_url, token, timeout, max_retries)
|
|
70
|
+
self._external = http_client
|
|
71
|
+
# An httpx client can't outlive the loop it was first used on, and
|
|
72
|
+
# applications and tests often run several loops.
|
|
73
|
+
self._clients: dict[asyncio.AbstractEventLoop, httpx.AsyncClient] = {}
|
|
74
|
+
self.sessions: AsyncSessions = AsyncSessions(self)
|
|
75
|
+
self.runs: AsyncRuns = AsyncRuns(self)
|
|
76
|
+
self.blueprints: AsyncBlueprints = AsyncBlueprints(self)
|
|
77
|
+
|
|
78
|
+
@property
|
|
79
|
+
def base_url(self) -> str:
|
|
80
|
+
return self._settings.base_url
|
|
81
|
+
|
|
82
|
+
async def execute(
|
|
83
|
+
self,
|
|
84
|
+
blueprint: str,
|
|
85
|
+
code: str,
|
|
86
|
+
*,
|
|
87
|
+
variables: Mapping[str, str] | None = None,
|
|
88
|
+
secrets: Mapping[str, str] | None = None,
|
|
89
|
+
) -> ExecuteResult:
|
|
90
|
+
"""`POST /v1/execute`: run one program in a session that ends when it returns.
|
|
91
|
+
|
|
92
|
+
An unknown Blueprint or invalid variables come back as the result's
|
|
93
|
+
`error`, not as an exception. One-off runs have no application tools.
|
|
94
|
+
"""
|
|
95
|
+
return b.read_execute_result(await self._send(b.execute_once(blueprint, code, variables, secrets)))
|
|
96
|
+
|
|
97
|
+
async def aclose(self) -> None:
|
|
98
|
+
"""Close the connections this client opened."""
|
|
99
|
+
clients, self._clients = list(self._clients.values()), {}
|
|
100
|
+
for client in clients:
|
|
101
|
+
if not client.is_closed:
|
|
102
|
+
await client.aclose()
|
|
103
|
+
|
|
104
|
+
async def __aenter__(self) -> AsyncSubmilli:
|
|
105
|
+
return self
|
|
106
|
+
|
|
107
|
+
async def __aexit__(
|
|
108
|
+
self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
|
|
109
|
+
) -> None:
|
|
110
|
+
await self.aclose()
|
|
111
|
+
|
|
112
|
+
def _http(self) -> httpx.AsyncClient:
|
|
113
|
+
if self._external is not None:
|
|
114
|
+
return self._external
|
|
115
|
+
loop = asyncio.get_running_loop()
|
|
116
|
+
for stale in [other for other in self._clients if other.is_closed()]:
|
|
117
|
+
del self._clients[stale]
|
|
118
|
+
client = self._clients.get(loop)
|
|
119
|
+
if client is None:
|
|
120
|
+
client = httpx.AsyncClient(timeout=self._settings.timeout)
|
|
121
|
+
self._clients[loop] = client
|
|
122
|
+
return client
|
|
123
|
+
|
|
124
|
+
async def _send(self, request: b.Request) -> httpx.Response:
|
|
125
|
+
headers = {**self._settings.headers(), **(request.headers or {})}
|
|
126
|
+
url = f"{self._settings.base_url}{request.path}"
|
|
127
|
+
attempts = 1 + (self._settings.max_retries if request.retryable else 0)
|
|
128
|
+
for attempt in range(attempts):
|
|
129
|
+
last = attempt == attempts - 1
|
|
130
|
+
response: httpx.Response | None = None
|
|
131
|
+
try:
|
|
132
|
+
response = await self._http().request(
|
|
133
|
+
request.method, url, json=request.json, params=request.params, headers=headers
|
|
134
|
+
)
|
|
135
|
+
except httpx.TimeoutException as error:
|
|
136
|
+
if last:
|
|
137
|
+
raise APITimeoutError(f"request to {url} timed out", request=error.request) from error
|
|
138
|
+
except httpx.TransportError as error:
|
|
139
|
+
if last:
|
|
140
|
+
raise APIConnectionError(f"could not reach {url}: {error}", request=error.request) from error
|
|
141
|
+
else:
|
|
142
|
+
if last or not b.should_retry(response):
|
|
143
|
+
return response
|
|
144
|
+
await asyncio.sleep(b.retry_delay(attempt, response))
|
|
145
|
+
raise AssertionError("unreachable")
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
class AsyncSessions:
|
|
149
|
+
"""Sessions: a Blueprint bound to variables and secrets, where programs run one after another."""
|
|
150
|
+
|
|
151
|
+
def __init__(self, client: AsyncSubmilli) -> None:
|
|
152
|
+
self._client = client
|
|
153
|
+
|
|
154
|
+
async def create(
|
|
155
|
+
self,
|
|
156
|
+
blueprint: str,
|
|
157
|
+
*,
|
|
158
|
+
variables: Mapping[str, str] | None = None,
|
|
159
|
+
secrets: Mapping[str, str] | None = None,
|
|
160
|
+
tools: Sequence[ToolDeclaration] | None = None,
|
|
161
|
+
) -> CreatedSession:
|
|
162
|
+
"""`POST /v1/sessions`: open a session.
|
|
163
|
+
|
|
164
|
+
`tools` are the application's tools that programs may call as `@tools`,
|
|
165
|
+
fixed for the session's life. The Blueprint must grant `tools.call`.
|
|
166
|
+
"""
|
|
167
|
+
return b.read_created_session(await self._client._send(b.create_session(blueprint, variables, secrets, tools)))
|
|
168
|
+
|
|
169
|
+
async def execute(self, session_id: str, code: str, *, idempotency_key: str | None = None) -> RunState:
|
|
170
|
+
"""`POST /v1/sessions/{id}/execute`: start a program and answer its first state.
|
|
171
|
+
|
|
172
|
+
In a session with application tools a run may answer `SuspendedRun`;
|
|
173
|
+
`run` answers its calls for you. With an `idempotency_key`, a repeated
|
|
174
|
+
request answers the same run instead of running the program again.
|
|
175
|
+
"""
|
|
176
|
+
return b.read_run_state(await self._client._send(b.execute(session_id, code, idempotency_key)))
|
|
177
|
+
|
|
178
|
+
async def run(
|
|
179
|
+
self,
|
|
180
|
+
session_id: str,
|
|
181
|
+
code: str,
|
|
182
|
+
*,
|
|
183
|
+
idempotency_key: str | None = None,
|
|
184
|
+
on_tool_call: AsyncToolHandler | None = None,
|
|
185
|
+
) -> ExecuteResult:
|
|
186
|
+
"""Run a program to the end, answering its calls to the application's tools with `on_tool_call`.
|
|
187
|
+
|
|
188
|
+
An exception from `on_tool_call` propagates and leaves the run waiting
|
|
189
|
+
on the server. Executing again with the same `idempotency_key` picks it
|
|
190
|
+
up at the call it waits on.
|
|
191
|
+
"""
|
|
192
|
+
state = await self.execute(session_id, code, idempotency_key=idempotency_key)
|
|
193
|
+
return await self._client.runs.complete(state, on_tool_call=on_tool_call)
|
|
194
|
+
|
|
195
|
+
async def rebind(self, session_id: str, secrets: Mapping[str, str]) -> None:
|
|
196
|
+
"""`POST /v1/sessions/{id}/rebind`: replace the session's harness secrets, as after a server restart."""
|
|
197
|
+
b.read_no_content(await self._client._send(b.rebind(session_id, secrets)))
|
|
198
|
+
|
|
199
|
+
async def last_run(self, session_id: str) -> LastRun | None:
|
|
200
|
+
"""`GET /v1/sessions/{id}/last-run`. `None` when no run is recorded or the session is unknown."""
|
|
201
|
+
return b.read_last_run(await self._client._send(b.last_run(session_id)))
|
|
202
|
+
|
|
203
|
+
async def delete(self, session_id: str) -> bool:
|
|
204
|
+
"""`DELETE /v1/sessions/{id}`: end the session. `False` when it had already ended."""
|
|
205
|
+
return b.read_deleted(await self._client._send(b.delete_session(session_id)))
|
|
206
|
+
|
|
207
|
+
async def search_packages(self, session_id: str, query: str = "") -> dict[str, Any]:
|
|
208
|
+
"""The Blueprint's Package search, plus the session's own `@tools`."""
|
|
209
|
+
return b.read_json(await self._client._send(b.session_packages_search(session_id, query)))
|
|
210
|
+
|
|
211
|
+
async def package_docs(self, session_id: str, name: str) -> PackageDocs:
|
|
212
|
+
"""A Package's docs, where `@tools` is the session's own."""
|
|
213
|
+
return b.read_package_docs(await self._client._send(b.session_packages_docs(session_id, name)))
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
class AsyncRuns:
|
|
217
|
+
"""Runs that wait on the application's tools."""
|
|
218
|
+
|
|
219
|
+
def __init__(self, client: AsyncSubmilli) -> None:
|
|
220
|
+
self._client = client
|
|
221
|
+
|
|
222
|
+
async def resume(self, run_id: str, results: Sequence[ToolResult]) -> RunState:
|
|
223
|
+
"""`POST /v1/runs/{id}/resume`: answer the run's pending calls, then wait for its next state.
|
|
224
|
+
|
|
225
|
+
Answering a call twice changes nothing. Raises `UnknownRunError`,
|
|
226
|
+
`RunNotSuspendedError` and `UnknownCallError`.
|
|
227
|
+
"""
|
|
228
|
+
return b.read_run_state(await self._client._send(b.resume(run_id, results)))
|
|
229
|
+
|
|
230
|
+
async def retrieve(self, run_id: str) -> RunState:
|
|
231
|
+
"""`GET /v1/runs/{id}`: the run's state now. Raises `UnknownRunError`."""
|
|
232
|
+
return b.read_run_state(await self._client._send(b.retrieve_run(run_id)))
|
|
233
|
+
|
|
234
|
+
async def complete(
|
|
235
|
+
self,
|
|
236
|
+
state: RunState,
|
|
237
|
+
*,
|
|
238
|
+
on_tool_call: AsyncToolHandler | None = None,
|
|
239
|
+
poll_interval: float = 0.1,
|
|
240
|
+
max_poll_interval: float = 2.0,
|
|
241
|
+
) -> ExecuteResult:
|
|
242
|
+
"""Drive a run from `state` until it finishes.
|
|
243
|
+
|
|
244
|
+
Each pending call goes to `on_tool_call`, sync or async, and its
|
|
245
|
+
`ToolResult` goes back with `resume`. A run that is `running` is polled.
|
|
246
|
+
Raises `UnknownRunError` when the server lost the run, as after a restart.
|
|
247
|
+
"""
|
|
248
|
+
delay = poll_interval
|
|
249
|
+
while not isinstance(state, ExecuteResult):
|
|
250
|
+
if isinstance(state, RunningRun):
|
|
251
|
+
await asyncio.sleep(delay)
|
|
252
|
+
delay = min(delay * 2, max_poll_interval)
|
|
253
|
+
state = await self.retrieve(state.execution_id)
|
|
254
|
+
continue
|
|
255
|
+
if on_tool_call is None:
|
|
256
|
+
raise SubmilliError(
|
|
257
|
+
f"run {state.execution_id} called the application's tool {state.calls[0].tool!r}, "
|
|
258
|
+
"and no on_tool_call was given to answer it"
|
|
259
|
+
)
|
|
260
|
+
results = []
|
|
261
|
+
for call in state.calls:
|
|
262
|
+
result = on_tool_call(call)
|
|
263
|
+
if inspect.isawaitable(result):
|
|
264
|
+
result = await result
|
|
265
|
+
if not isinstance(result, ToolResult) or result.call_id != call.call_id:
|
|
266
|
+
raise SubmilliError(f"on_tool_call must return a ToolResult for call {call.call_id!r}")
|
|
267
|
+
results.append(result)
|
|
268
|
+
try:
|
|
269
|
+
state = await self.resume(state.execution_id, results)
|
|
270
|
+
except (RunNotSuspendedError, UnknownCallError):
|
|
271
|
+
# A call timed out, or another attempt answered it: look again.
|
|
272
|
+
state = await self.retrieve(state.execution_id)
|
|
273
|
+
return state
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
class AsyncBlueprints:
|
|
277
|
+
"""What a model needs to write programs for one Blueprint."""
|
|
278
|
+
|
|
279
|
+
def __init__(self, client: AsyncSubmilli) -> None:
|
|
280
|
+
self._client = client
|
|
281
|
+
|
|
282
|
+
async def prompt(self, blueprint: str) -> BlueprintPrompt:
|
|
283
|
+
"""`GET /v1/blueprints/{name}/prompt`: the tool descriptions the server writes for this Blueprint."""
|
|
284
|
+
return b.read_prompt(await self._client._send(b.prompt(blueprint)))
|
|
285
|
+
|
|
286
|
+
async def search_packages(self, blueprint: str, query: str = "") -> dict[str, Any]:
|
|
287
|
+
"""`GET /v1/blueprints/{name}/packages/search`. An empty query lists every Package."""
|
|
288
|
+
return b.read_json(await self._client._send(b.packages_search(blueprint, query)))
|
|
289
|
+
|
|
290
|
+
async def package_docs(self, blueprint: str, name: str) -> PackageDocs:
|
|
291
|
+
"""`GET /v1/blueprints/{name}/packages/docs`."""
|
|
292
|
+
return b.read_package_docs(await self._client._send(b.packages_docs(blueprint, name)))
|
|
293
|
+
|
|
294
|
+
async def builtins(self, blueprint: str) -> dict[str, Any]:
|
|
295
|
+
"""`GET /v1/blueprints/{name}/builtins`: the built-ins in scope without an import."""
|
|
296
|
+
return b.read_json(await self._client._send(b.builtins(blueprint)))
|
|
297
|
+
|
|
298
|
+
async def builtin_docs(self, blueprint: str, names: Sequence[str]) -> dict[str, Any]:
|
|
299
|
+
"""`GET /v1/blueprints/{name}/builtins/docs`: declarations of built-ins."""
|
|
300
|
+
return b.read_json(await self._client._send(b.builtins_docs(blueprint, names)))
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
__all__ = ["AsyncBlueprints", "AsyncRuns", "AsyncSessions", "AsyncSubmilli", "AsyncToolHandler"]
|
submilli/_base.py
ADDED
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
"""What the sync and async clients share: settings, the requests, and how answers are read.
|
|
2
|
+
|
|
3
|
+
Each endpoint is a request builder and a reader, so that `Submilli` and
|
|
4
|
+
`AsyncSubmilli` differ only in how they send.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import hashlib
|
|
10
|
+
import os
|
|
11
|
+
import random
|
|
12
|
+
from collections.abc import Mapping, Sequence
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from typing import Any
|
|
15
|
+
from urllib.parse import quote
|
|
16
|
+
|
|
17
|
+
import httpx
|
|
18
|
+
|
|
19
|
+
from submilli._errors import IDEMPOTENCY_CODES, UnknownSessionError, status_error
|
|
20
|
+
from submilli._types import (
|
|
21
|
+
BlueprintPrompt,
|
|
22
|
+
CreatedSession,
|
|
23
|
+
ExecuteResult,
|
|
24
|
+
LastRun,
|
|
25
|
+
PackageDocs,
|
|
26
|
+
RunState,
|
|
27
|
+
ToolDeclaration,
|
|
28
|
+
ToolResult,
|
|
29
|
+
run_state,
|
|
30
|
+
)
|
|
31
|
+
from submilli._version import __version__
|
|
32
|
+
|
|
33
|
+
DEFAULT_BASE_URL = "http://127.0.0.1:8128"
|
|
34
|
+
# An execute may wait up to 300 seconds on the server for an earlier attempt
|
|
35
|
+
# with the same idempotency key; leave room for that.
|
|
36
|
+
DEFAULT_TIMEOUT = 330.0
|
|
37
|
+
DEFAULT_MAX_RETRIES = 2
|
|
38
|
+
# The longest `Idempotency-Key` the server accepts, in bytes.
|
|
39
|
+
MAX_IDEMPOTENCY_KEY_BYTES = 120
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def idempotency_key(call_id: str) -> str:
|
|
43
|
+
"""An `Idempotency-Key` for a harness's own call id, such as a model's tool call id.
|
|
44
|
+
|
|
45
|
+
The id as is when the server accepts it (printable ASCII, 1 to 120 bytes),
|
|
46
|
+
otherwise the sha256 hex digest of its UTF-8 bytes. The same id always gives
|
|
47
|
+
the same key.
|
|
48
|
+
"""
|
|
49
|
+
if 0 < len(call_id) <= MAX_IDEMPOTENCY_KEY_BYTES and all(" " <= char <= "~" for char in call_id):
|
|
50
|
+
return call_id
|
|
51
|
+
return hashlib.sha256(call_id.encode("utf-8")).hexdigest()
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass(frozen=True, slots=True)
|
|
55
|
+
class Settings:
|
|
56
|
+
base_url: str
|
|
57
|
+
token: str | None
|
|
58
|
+
timeout: float | httpx.Timeout
|
|
59
|
+
max_retries: int
|
|
60
|
+
|
|
61
|
+
@classmethod
|
|
62
|
+
def resolve(
|
|
63
|
+
cls, base_url: str | None, token: str | None, timeout: float | httpx.Timeout, max_retries: int
|
|
64
|
+
) -> Settings:
|
|
65
|
+
if max_retries < 0:
|
|
66
|
+
raise ValueError("max_retries must be 0 or more")
|
|
67
|
+
return cls(
|
|
68
|
+
base_url=(base_url or os.environ.get("SUBMILLI_SERVER") or DEFAULT_BASE_URL).rstrip("/"),
|
|
69
|
+
token=token if token is not None else os.environ.get("SUBMILLI_SERVER_TOKEN"),
|
|
70
|
+
timeout=timeout,
|
|
71
|
+
max_retries=max_retries,
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
def headers(self) -> dict[str, str]:
|
|
75
|
+
headers = {"User-Agent": f"submilli-python/{__version__}", "Accept": "application/json"}
|
|
76
|
+
if self.token:
|
|
77
|
+
headers["Authorization"] = f"Bearer {self.token}"
|
|
78
|
+
return headers
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@dataclass(frozen=True, slots=True)
|
|
82
|
+
class Request:
|
|
83
|
+
method: str
|
|
84
|
+
path: str
|
|
85
|
+
json: Any = None
|
|
86
|
+
params: Any = None
|
|
87
|
+
headers: Mapping[str, str] | None = None
|
|
88
|
+
#: Whether sending it twice is harmless, so a failed attempt may be retried.
|
|
89
|
+
retryable: bool = False
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def should_retry(response: httpx.Response) -> bool:
|
|
93
|
+
"""Whether a response is a transient failure worth another attempt."""
|
|
94
|
+
if response.status_code not in (502, 503, 504):
|
|
95
|
+
return False
|
|
96
|
+
try:
|
|
97
|
+
code = response.json().get("error")
|
|
98
|
+
except (ValueError, AttributeError):
|
|
99
|
+
return True
|
|
100
|
+
# An idempotency refusal is the server's answer, not a transient failure.
|
|
101
|
+
return code not in IDEMPOTENCY_CODES
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def retry_delay(attempt: int, response: httpx.Response | None) -> float:
|
|
105
|
+
if response is not None:
|
|
106
|
+
after = response.headers.get("retry-after")
|
|
107
|
+
if after is not None:
|
|
108
|
+
try:
|
|
109
|
+
return min(float(after), 30.0)
|
|
110
|
+
except ValueError:
|
|
111
|
+
pass
|
|
112
|
+
return min(0.5 * 2.0**attempt, 8.0) * (0.75 + random.random() / 2)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _seg(value: str) -> str:
|
|
116
|
+
return quote(value, safe="")
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _json(response: httpx.Response) -> Any:
|
|
120
|
+
if not response.is_success:
|
|
121
|
+
raise status_error(response)
|
|
122
|
+
return response.json()
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
# Sessions
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def create_session(
|
|
129
|
+
blueprint: str,
|
|
130
|
+
variables: Mapping[str, str] | None,
|
|
131
|
+
secrets: Mapping[str, str] | None,
|
|
132
|
+
tools: Sequence[ToolDeclaration] | None,
|
|
133
|
+
) -> Request:
|
|
134
|
+
body: dict[str, Any] = {"blueprint": blueprint, "variables": dict(variables or {})}
|
|
135
|
+
if secrets:
|
|
136
|
+
body["secrets"] = dict(secrets)
|
|
137
|
+
if tools:
|
|
138
|
+
body["tools"] = [dict(tool) for tool in tools]
|
|
139
|
+
# Not retried: a lost answer would leave a session nobody holds.
|
|
140
|
+
return Request("POST", "/v1/sessions", json=body)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def read_created_session(response: httpx.Response) -> CreatedSession:
|
|
144
|
+
body = _json(response)
|
|
145
|
+
return CreatedSession(id=str(body["session_id"]), warnings=[str(w) for w in body.get("warnings") or []])
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def execute(session_id: str, code: str, key: str | None) -> Request:
|
|
149
|
+
return Request(
|
|
150
|
+
"POST",
|
|
151
|
+
f"/v1/sessions/{_seg(session_id)}/execute",
|
|
152
|
+
json={"code": code},
|
|
153
|
+
headers={"Idempotency-Key": key} if key else None,
|
|
154
|
+
# Without a key, a retry could run the program twice.
|
|
155
|
+
retryable=key is not None,
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def read_run_state(response: httpx.Response) -> RunState:
|
|
160
|
+
return run_state(_json(response))
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def rebind(session_id: str, secrets: Mapping[str, str]) -> Request:
|
|
164
|
+
return Request("POST", f"/v1/sessions/{_seg(session_id)}/rebind", json={"secrets": dict(secrets)}, retryable=True)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def read_no_content(response: httpx.Response) -> None:
|
|
168
|
+
if not response.is_success:
|
|
169
|
+
raise status_error(response)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def last_run(session_id: str) -> Request:
|
|
173
|
+
return Request("GET", f"/v1/sessions/{_seg(session_id)}/last-run", retryable=True)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def read_last_run(response: httpx.Response) -> LastRun | None:
|
|
177
|
+
# The server answers 404 with an empty body both for an unknown session and
|
|
178
|
+
# for a session with no recorded run.
|
|
179
|
+
if response.status_code == 404:
|
|
180
|
+
return None
|
|
181
|
+
return LastRun._from_json(_json(response))
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def delete_session(session_id: str) -> Request:
|
|
185
|
+
return Request("DELETE", f"/v1/sessions/{_seg(session_id)}", retryable=True)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def read_deleted(response: httpx.Response) -> bool:
|
|
189
|
+
if response.status_code == 404:
|
|
190
|
+
return False
|
|
191
|
+
read_no_content(response)
|
|
192
|
+
return True
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def session_packages_search(session_id: str, query: str) -> Request:
|
|
196
|
+
return Request("GET", f"/v1/sessions/{_seg(session_id)}/packages/search", params={"q": query}, retryable=True)
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def session_packages_docs(session_id: str, name: str) -> Request:
|
|
200
|
+
return Request("GET", f"/v1/sessions/{_seg(session_id)}/packages/docs", params={"name": name}, retryable=True)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
# Runs
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def resume(run_id: str, results: Sequence[ToolResult]) -> Request:
|
|
207
|
+
if not results:
|
|
208
|
+
raise ValueError("resume needs at least one result")
|
|
209
|
+
# Answering a call twice changes nothing, so a resume may be retried.
|
|
210
|
+
body = {"results": [result.to_json() for result in results]}
|
|
211
|
+
return Request("POST", f"/v1/runs/{_seg(run_id)}/resume", json=body, retryable=True)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def retrieve_run(run_id: str) -> Request:
|
|
215
|
+
return Request("GET", f"/v1/runs/{_seg(run_id)}", retryable=True)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
# Blueprints
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def prompt(blueprint: str) -> Request:
|
|
222
|
+
return Request("GET", f"/v1/blueprints/{_seg(blueprint)}/prompt", retryable=True)
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def read_prompt(response: httpx.Response) -> BlueprintPrompt:
|
|
226
|
+
return BlueprintPrompt._from_json(_json(response))
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def packages_search(blueprint: str, query: str) -> Request:
|
|
230
|
+
return Request("GET", f"/v1/blueprints/{_seg(blueprint)}/packages/search", params={"q": query}, retryable=True)
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def packages_docs(blueprint: str, name: str) -> Request:
|
|
234
|
+
return Request("GET", f"/v1/blueprints/{_seg(blueprint)}/packages/docs", params={"name": name}, retryable=True)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def read_json(response: httpx.Response) -> dict[str, Any]:
|
|
238
|
+
body = _json(response)
|
|
239
|
+
if not isinstance(body, dict):
|
|
240
|
+
raise TypeError(f"expected a JSON object from submilli-server, got {type(body).__name__}")
|
|
241
|
+
return body
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def read_package_docs(response: httpx.Response) -> PackageDocs:
|
|
245
|
+
if response.status_code == 200:
|
|
246
|
+
return PackageDocs(found=True, text=response.text)
|
|
247
|
+
if response.status_code == 404:
|
|
248
|
+
error = status_error(response)
|
|
249
|
+
if isinstance(error, UnknownSessionError) or error.code == "not_found":
|
|
250
|
+
# An unknown session, or an unknown Blueprint: the caller's mistake.
|
|
251
|
+
raise error
|
|
252
|
+
return PackageDocs(found=False, text=response.text)
|
|
253
|
+
raise status_error(response)
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def builtins(blueprint: str) -> Request:
|
|
257
|
+
return Request("GET", f"/v1/blueprints/{_seg(blueprint)}/builtins", retryable=True)
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def builtins_docs(blueprint: str, names: Sequence[str]) -> Request:
|
|
261
|
+
return Request(
|
|
262
|
+
"GET",
|
|
263
|
+
f"/v1/blueprints/{_seg(blueprint)}/builtins/docs",
|
|
264
|
+
params=[("name", name) for name in names],
|
|
265
|
+
retryable=True,
|
|
266
|
+
)
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
# One-off runs
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
def execute_once(
|
|
273
|
+
blueprint: str, code: str, variables: Mapping[str, str] | None, secrets: Mapping[str, str] | None
|
|
274
|
+
) -> Request:
|
|
275
|
+
body: dict[str, Any] = {"blueprint": blueprint, "code": code, "variables": dict(variables or {})}
|
|
276
|
+
if secrets:
|
|
277
|
+
body["secrets"] = dict(secrets)
|
|
278
|
+
return Request("POST", "/v1/execute", json=body)
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def read_execute_result(response: httpx.Response) -> ExecuteResult:
|
|
282
|
+
return ExecuteResult._from_json(_json(response))
|