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 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))