devupai 1.0.0a1__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,347 @@
1
+ """Native inference: ``POST /inference/{model_path}``, a model-specific payload sent as it is."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from typing import Literal, overload
7
+
8
+ from devupai._response import APIResponse, AsyncBinaryResponse, BinaryResponse
9
+ from devupai.resources._base import (
10
+ AsyncAPIResource,
11
+ SyncAPIResource,
12
+ billed_post_retry,
13
+ encode_model_path,
14
+ endpoint,
15
+ json_body,
16
+ options,
17
+ with_data,
18
+ )
19
+ from devupai.resources.shared import MultipartPart, contains_file_input, every_field_form
20
+
21
+ __all__ = [
22
+ "NativeInference",
23
+ "AsyncNativeInference",
24
+ "NativeInferenceWithResponse",
25
+ "AsyncNativeInferenceWithResponse",
26
+ ]
27
+
28
+ _PATH_TEMPLATE = "/inference/{model_path}"
29
+ _PAYLOAD_MESSAGE = "The payload of inference.run must be a mapping of field names to values."
30
+
31
+ ResponseType = Literal["json", "binary"]
32
+ """How the answer of :meth:`NativeInference.run` is read: parsed as JSON, or as a file."""
33
+
34
+
35
+ def _prepare(
36
+ model_path: str,
37
+ payload: Mapping[str, object],
38
+ extra_body: Mapping[str, object] | None,
39
+ ) -> tuple[str, dict[str, object] | None, list[MultipartPart] | None]:
40
+ """The path of a call, and its JSON body or, when a field is a file (or a list contains one), the multipart
41
+ parts of every field."""
42
+ if not isinstance(payload, Mapping): # pyright: ignore[reportUnnecessaryIsInstance]
43
+ raise TypeError(_PAYLOAD_MESSAGE)
44
+ path = f"/inference/{encode_model_path(model_path)}"
45
+ body = json_body(payload, extra_body)
46
+ if any(contains_file_input(value) for value in body.values()):
47
+ return path, None, every_field_form(body)
48
+ return path, body, None
49
+
50
+
51
+ class NativeInferenceWithResponse(SyncAPIResource):
52
+ """The methods of :class:`NativeInference`, returning the whole :class:`~devupai.APIResponse`."""
53
+
54
+ @overload
55
+ def run(
56
+ self,
57
+ model_path: str,
58
+ payload: Mapping[str, object],
59
+ *,
60
+ response_type: Literal["binary"],
61
+ extra_headers: Mapping[str, str] | None = None,
62
+ timeout: float | None = None,
63
+ max_retries: int | None = None,
64
+ extra_body: Mapping[str, object] | None = None,
65
+ ) -> APIResponse[BinaryResponse]: ...
66
+ @overload
67
+ def run(
68
+ self,
69
+ model_path: str,
70
+ payload: Mapping[str, object],
71
+ *,
72
+ response_type: Literal["json"] = "json",
73
+ extra_headers: Mapping[str, str] | None = None,
74
+ timeout: float | None = None,
75
+ max_retries: int | None = None,
76
+ extra_body: Mapping[str, object] | None = None,
77
+ ) -> APIResponse[object]: ...
78
+ @overload
79
+ def run(
80
+ self,
81
+ model_path: str,
82
+ payload: Mapping[str, object],
83
+ *,
84
+ response_type: ResponseType = "json",
85
+ extra_headers: Mapping[str, str] | None = None,
86
+ timeout: float | None = None,
87
+ max_retries: int | None = None,
88
+ extra_body: Mapping[str, object] | None = None,
89
+ ) -> APIResponse[object] | APIResponse[BinaryResponse]: ...
90
+ @endpoint("POST", _PATH_TEMPLATE, billed=True)
91
+ def run(
92
+ self,
93
+ model_path: str,
94
+ payload: Mapping[str, object],
95
+ *,
96
+ response_type: ResponseType = "json",
97
+ extra_headers: Mapping[str, str] | None = None,
98
+ timeout: float | None = None,
99
+ max_retries: int | None = None,
100
+ extra_body: Mapping[str, object] | None = None,
101
+ ) -> APIResponse[object] | APIResponse[BinaryResponse]:
102
+ """Sends a model-specific payload to a model; see :meth:`NativeInference.run`."""
103
+ path, body, parts = _prepare(model_path, payload, extra_body)
104
+ binary = response_type == "binary"
105
+ response = self._send(
106
+ "POST",
107
+ path,
108
+ body=body,
109
+ multipart=parts,
110
+ retry=billed_post_retry(),
111
+ kind="raw" if binary else "json",
112
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
113
+ )
114
+ if binary:
115
+ return with_data(response, BinaryResponse(response.response))
116
+ return response
117
+
118
+
119
+ class NativeInference(SyncAPIResource):
120
+ """Native inference: ``POST /inference/{model_path}``."""
121
+
122
+ @property
123
+ def with_response(self) -> NativeInferenceWithResponse:
124
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
125
+ return NativeInferenceWithResponse(self._client)
126
+
127
+ @overload
128
+ def run(
129
+ self,
130
+ model_path: str,
131
+ payload: Mapping[str, object],
132
+ *,
133
+ response_type: Literal["binary"],
134
+ extra_headers: Mapping[str, str] | None = None,
135
+ timeout: float | None = None,
136
+ max_retries: int | None = None,
137
+ extra_body: Mapping[str, object] | None = None,
138
+ ) -> BinaryResponse: ...
139
+ @overload
140
+ def run(
141
+ self,
142
+ model_path: str,
143
+ payload: Mapping[str, object],
144
+ *,
145
+ response_type: ResponseType = "json",
146
+ extra_headers: Mapping[str, str] | None = None,
147
+ timeout: float | None = None,
148
+ max_retries: int | None = None,
149
+ extra_body: Mapping[str, object] | None = None,
150
+ ) -> object: ...
151
+ @endpoint("POST", _PATH_TEMPLATE, billed=True)
152
+ def run(
153
+ self,
154
+ model_path: str,
155
+ payload: Mapping[str, object],
156
+ *,
157
+ response_type: ResponseType = "json",
158
+ extra_headers: Mapping[str, str] | None = None,
159
+ timeout: float | None = None,
160
+ max_retries: int | None = None,
161
+ extra_body: Mapping[str, object] | None = None,
162
+ ) -> object:
163
+ """Sends a model-specific payload to a model and returns its result.
164
+
165
+ ``model_path`` is the model id: leading slashes are removed, and an id that is already percent-encoded is
166
+ decoded first, so it is sent as one path segment encoded exactly once.
167
+
168
+ The payload is sent as JSON, as it is. When a field is a file (bytes, a path, an open binary file or a
169
+ ``(filename, content[, content_type])`` tuple), or a list contains one, the payload is sent as
170
+ ``multipart/form-data`` instead: a file is a file part, a ``str`` a text part, a list gives one part per item
171
+ under the field name, a mapping is sent as its JSON text and a number or a boolean as text. A path is opened
172
+ and closed by the SDK; an open file is read and left open.
173
+
174
+ The answer is parsed as JSON. With ``response_type="binary"``, for a model that answers with a file (an
175
+ image, an audio clip or a video), it is returned as a :class:`~devupai.BinaryResponse` with its body not
176
+ read yet.
177
+
178
+ ``extra_body`` adds fields to the payload (merged last), ``extra_headers`` adds request headers, and
179
+ ``timeout`` and ``max_retries`` apply to this call only.
180
+
181
+ Example::
182
+
183
+ result = client.inference.run("<model-id>", {"input": "Hello"})
184
+
185
+ with client.inference.run("<model-id>", {"prompt": "A sunrise"}, response_type="binary") as image:
186
+ image.write_to_file("sunrise.png")
187
+ """
188
+ return self.with_response.run(
189
+ model_path,
190
+ payload,
191
+ response_type=response_type,
192
+ extra_headers=extra_headers,
193
+ timeout=timeout,
194
+ max_retries=max_retries,
195
+ extra_body=extra_body,
196
+ ).data
197
+
198
+
199
+ class AsyncNativeInferenceWithResponse(AsyncAPIResource):
200
+ """The methods of :class:`AsyncNativeInference`, returning the whole :class:`~devupai.APIResponse`."""
201
+
202
+ @overload
203
+ async def run(
204
+ self,
205
+ model_path: str,
206
+ payload: Mapping[str, object],
207
+ *,
208
+ response_type: Literal["binary"],
209
+ extra_headers: Mapping[str, str] | None = None,
210
+ timeout: float | None = None,
211
+ max_retries: int | None = None,
212
+ extra_body: Mapping[str, object] | None = None,
213
+ ) -> APIResponse[AsyncBinaryResponse]: ...
214
+ @overload
215
+ async def run(
216
+ self,
217
+ model_path: str,
218
+ payload: Mapping[str, object],
219
+ *,
220
+ response_type: Literal["json"] = "json",
221
+ extra_headers: Mapping[str, str] | None = None,
222
+ timeout: float | None = None,
223
+ max_retries: int | None = None,
224
+ extra_body: Mapping[str, object] | None = None,
225
+ ) -> APIResponse[object]: ...
226
+ @overload
227
+ async def run(
228
+ self,
229
+ model_path: str,
230
+ payload: Mapping[str, object],
231
+ *,
232
+ response_type: ResponseType = "json",
233
+ extra_headers: Mapping[str, str] | None = None,
234
+ timeout: float | None = None,
235
+ max_retries: int | None = None,
236
+ extra_body: Mapping[str, object] | None = None,
237
+ ) -> APIResponse[object] | APIResponse[AsyncBinaryResponse]: ...
238
+ @endpoint("POST", _PATH_TEMPLATE, billed=True)
239
+ async def run(
240
+ self,
241
+ model_path: str,
242
+ payload: Mapping[str, object],
243
+ *,
244
+ response_type: ResponseType = "json",
245
+ extra_headers: Mapping[str, str] | None = None,
246
+ timeout: float | None = None,
247
+ max_retries: int | None = None,
248
+ extra_body: Mapping[str, object] | None = None,
249
+ ) -> APIResponse[object] | APIResponse[AsyncBinaryResponse]:
250
+ """Sends a model-specific payload to a model; see :meth:`AsyncNativeInference.run`."""
251
+ path, body, parts = _prepare(model_path, payload, extra_body)
252
+ binary = response_type == "binary"
253
+ response = await self._send(
254
+ "POST",
255
+ path,
256
+ body=body,
257
+ multipart=parts,
258
+ retry=billed_post_retry(),
259
+ kind="raw" if binary else "json",
260
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
261
+ )
262
+ if binary:
263
+ return with_data(response, AsyncBinaryResponse(response.response))
264
+ return response
265
+
266
+
267
+ class AsyncNativeInference(AsyncAPIResource):
268
+ """Native inference: ``POST /inference/{model_path}``."""
269
+
270
+ @property
271
+ def with_response(self) -> AsyncNativeInferenceWithResponse:
272
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
273
+ return AsyncNativeInferenceWithResponse(self._client)
274
+
275
+ @overload
276
+ async def run(
277
+ self,
278
+ model_path: str,
279
+ payload: Mapping[str, object],
280
+ *,
281
+ response_type: Literal["binary"],
282
+ extra_headers: Mapping[str, str] | None = None,
283
+ timeout: float | None = None,
284
+ max_retries: int | None = None,
285
+ extra_body: Mapping[str, object] | None = None,
286
+ ) -> AsyncBinaryResponse: ...
287
+ @overload
288
+ async def run(
289
+ self,
290
+ model_path: str,
291
+ payload: Mapping[str, object],
292
+ *,
293
+ response_type: ResponseType = "json",
294
+ extra_headers: Mapping[str, str] | None = None,
295
+ timeout: float | None = None,
296
+ max_retries: int | None = None,
297
+ extra_body: Mapping[str, object] | None = None,
298
+ ) -> object: ...
299
+ @endpoint("POST", _PATH_TEMPLATE, billed=True)
300
+ async def run(
301
+ self,
302
+ model_path: str,
303
+ payload: Mapping[str, object],
304
+ *,
305
+ response_type: ResponseType = "json",
306
+ extra_headers: Mapping[str, str] | None = None,
307
+ timeout: float | None = None,
308
+ max_retries: int | None = None,
309
+ extra_body: Mapping[str, object] | None = None,
310
+ ) -> object:
311
+ """Sends a model-specific payload to a model and returns its result.
312
+
313
+ ``model_path`` is the model id: leading slashes are removed, and an id that is already percent-encoded is
314
+ decoded first, so it is sent as one path segment encoded exactly once.
315
+
316
+ The payload is sent as JSON, as it is. When a field is a file (bytes, a path, an open binary file or a
317
+ ``(filename, content[, content_type])`` tuple), or a list contains one, the payload is sent as
318
+ ``multipart/form-data`` instead: a file is a file part, a ``str`` a text part, a list gives one part per item
319
+ under the field name, a mapping is sent as its JSON text and a number or a boolean as text. A path is opened
320
+ and closed by the SDK; an open file is read and left open.
321
+
322
+ The answer is parsed as JSON. With ``response_type="binary"``, for a model that answers with a file (an
323
+ image, an audio clip or a video), it is returned as an :class:`~devupai.AsyncBinaryResponse` with its body
324
+ not read yet.
325
+
326
+ ``extra_body`` adds fields to the payload (merged last), ``extra_headers`` adds request headers, and
327
+ ``timeout`` and ``max_retries`` apply to this call only.
328
+
329
+ Example::
330
+
331
+ result = await client.inference.run("<model-id>", {"input": "Hello"})
332
+
333
+ async with await client.inference.run(
334
+ "<model-id>", {"prompt": "A sunrise"}, response_type="binary"
335
+ ) as image:
336
+ await image.write_to_file("sunrise.png")
337
+ """
338
+ response = await self.with_response.run(
339
+ model_path,
340
+ payload,
341
+ response_type=response_type,
342
+ extra_headers=extra_headers,
343
+ timeout=timeout,
344
+ max_retries=max_retries,
345
+ extra_body=extra_body,
346
+ )
347
+ return response.data
@@ -0,0 +1,208 @@
1
+ """Account profile: ``GET /me`` and ``GET /me/avatar``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+
7
+ from devupai._response import APIResponse, AsyncBinaryResponse, BinaryResponse
8
+ from devupai.resources._base import (
9
+ AsyncAPIResource,
10
+ SyncAPIResource,
11
+ endpoint,
12
+ options,
13
+ with_data,
14
+ )
15
+ from devupai.types import AccountProfile
16
+ from devupai.types._base import parse_model
17
+
18
+ __all__ = ["Me", "AsyncMe", "MeWithResponse", "AsyncMeWithResponse"]
19
+
20
+ _PATH = "/me"
21
+ _AVATAR_PATH = "/me/avatar"
22
+
23
+
24
+ class MeWithResponse(SyncAPIResource):
25
+ """The methods of :class:`Me`, returning the whole :class:`~devupai.APIResponse`."""
26
+
27
+ @endpoint("GET", _PATH, billed=False)
28
+ def retrieve(
29
+ self,
30
+ *,
31
+ extra_headers: Mapping[str, str] | None = None,
32
+ timeout: float | None = None,
33
+ max_retries: int | None = None,
34
+ ) -> APIResponse[AccountProfile]:
35
+ """Retrieves the profile of the account that owns the API key; see :meth:`Me.retrieve`."""
36
+ response = self._send(
37
+ "GET", _PATH, options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers)
38
+ )
39
+ return with_data(response, parse_model(AccountProfile, response.data))
40
+
41
+ @endpoint("GET", _AVATAR_PATH, billed=False)
42
+ def avatar(
43
+ self,
44
+ *,
45
+ if_none_match: str | None = None,
46
+ extra_headers: Mapping[str, str] | None = None,
47
+ timeout: float | None = None,
48
+ max_retries: int | None = None,
49
+ ) -> APIResponse[BinaryResponse]:
50
+ """Fetches the account's profile picture; see :meth:`Me.avatar`."""
51
+ response = self._send(
52
+ "GET",
53
+ _AVATAR_PATH,
54
+ if_none_match=if_none_match,
55
+ kind="raw",
56
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
57
+ )
58
+ return with_data(response, BinaryResponse(response.response))
59
+
60
+
61
+ class Me(SyncAPIResource):
62
+ """Account profile: ``GET /me`` and ``GET /me/avatar``. Both use the API key."""
63
+
64
+ @property
65
+ def with_response(self) -> MeWithResponse:
66
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
67
+ return MeWithResponse(self._client)
68
+
69
+ @endpoint("GET", _PATH, billed=False)
70
+ def retrieve(
71
+ self,
72
+ *,
73
+ extra_headers: Mapping[str, str] | None = None,
74
+ timeout: float | None = None,
75
+ max_retries: int | None = None,
76
+ ) -> AccountProfile:
77
+ """Retrieves the profile of the account that owns the API key: a display name, an initial, a masked email
78
+ hint and, when the account has a picture, the URL and ``etag`` of the avatar.
79
+
80
+ Example::
81
+
82
+ profile = client.me.retrieve()
83
+ print(profile.display_name or profile.initial)
84
+ """
85
+ return self.with_response.retrieve(extra_headers=extra_headers, timeout=timeout, max_retries=max_retries).data
86
+
87
+ @endpoint("GET", _AVATAR_PATH, billed=False)
88
+ def avatar(
89
+ self,
90
+ *,
91
+ if_none_match: str | None = None,
92
+ extra_headers: Mapping[str, str] | None = None,
93
+ timeout: float | None = None,
94
+ max_retries: int | None = None,
95
+ ) -> BinaryResponse:
96
+ """Fetches the account's profile picture, as a :class:`~devupai.BinaryResponse` with its body not read yet.
97
+
98
+ Read the ``content-type`` and ``etag`` headers, and the bytes with ``read()``. With ``if_none_match`` set to
99
+ the ``etag`` of a copy you already have (from :meth:`retrieve` or an earlier ``ETag`` header), an unchanged
100
+ picture gives a result with ``status_code == 304`` and an empty body instead of the bytes.
101
+
102
+ An account without a picture raises :class:`~devupai.NotFoundError` (code ``avatar_not_found``).
103
+
104
+ Example::
105
+
106
+ with client.me.avatar() as avatar:
107
+ data = avatar.read()
108
+ etag = avatar.headers.get("etag")
109
+ """
110
+ return self.with_response.avatar(
111
+ if_none_match=if_none_match, extra_headers=extra_headers, timeout=timeout, max_retries=max_retries
112
+ ).data
113
+
114
+
115
+ class AsyncMeWithResponse(AsyncAPIResource):
116
+ """The methods of :class:`AsyncMe`, returning the whole :class:`~devupai.APIResponse`."""
117
+
118
+ @endpoint("GET", _PATH, billed=False)
119
+ async def retrieve(
120
+ self,
121
+ *,
122
+ extra_headers: Mapping[str, str] | None = None,
123
+ timeout: float | None = None,
124
+ max_retries: int | None = None,
125
+ ) -> APIResponse[AccountProfile]:
126
+ """Retrieves the profile of the account that owns the API key; see :meth:`AsyncMe.retrieve`."""
127
+ response = await self._send(
128
+ "GET", _PATH, options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers)
129
+ )
130
+ return with_data(response, parse_model(AccountProfile, response.data))
131
+
132
+ @endpoint("GET", _AVATAR_PATH, billed=False)
133
+ async def avatar(
134
+ self,
135
+ *,
136
+ if_none_match: str | None = None,
137
+ extra_headers: Mapping[str, str] | None = None,
138
+ timeout: float | None = None,
139
+ max_retries: int | None = None,
140
+ ) -> APIResponse[AsyncBinaryResponse]:
141
+ """Fetches the account's profile picture; see :meth:`AsyncMe.avatar`."""
142
+ response = await self._send(
143
+ "GET",
144
+ _AVATAR_PATH,
145
+ if_none_match=if_none_match,
146
+ kind="raw",
147
+ options=options(timeout=timeout, max_retries=max_retries, extra_headers=extra_headers),
148
+ )
149
+ return with_data(response, AsyncBinaryResponse(response.response))
150
+
151
+
152
+ class AsyncMe(AsyncAPIResource):
153
+ """Account profile: ``GET /me`` and ``GET /me/avatar``. Both use the API key."""
154
+
155
+ @property
156
+ def with_response(self) -> AsyncMeWithResponse:
157
+ """The same methods, returning the whole :class:`~devupai.APIResponse` (headers, request id, warnings)."""
158
+ return AsyncMeWithResponse(self._client)
159
+
160
+ @endpoint("GET", _PATH, billed=False)
161
+ async def retrieve(
162
+ self,
163
+ *,
164
+ extra_headers: Mapping[str, str] | None = None,
165
+ timeout: float | None = None,
166
+ max_retries: int | None = None,
167
+ ) -> AccountProfile:
168
+ """Retrieves the profile of the account that owns the API key: a display name, an initial, a masked email
169
+ hint and, when the account has a picture, the URL and ``etag`` of the avatar.
170
+
171
+ Example::
172
+
173
+ profile = await client.me.retrieve()
174
+ print(profile.display_name or profile.initial)
175
+ """
176
+ response = await self.with_response.retrieve(
177
+ extra_headers=extra_headers, timeout=timeout, max_retries=max_retries
178
+ )
179
+ return response.data
180
+
181
+ @endpoint("GET", _AVATAR_PATH, billed=False)
182
+ async def avatar(
183
+ self,
184
+ *,
185
+ if_none_match: str | None = None,
186
+ extra_headers: Mapping[str, str] | None = None,
187
+ timeout: float | None = None,
188
+ max_retries: int | None = None,
189
+ ) -> AsyncBinaryResponse:
190
+ """Fetches the account's profile picture, as an :class:`~devupai.AsyncBinaryResponse` with its body not read
191
+ yet.
192
+
193
+ Read the ``content-type`` and ``etag`` headers, and the bytes with ``await read()``. With ``if_none_match``
194
+ set to the ``etag`` of a copy you already have (from :meth:`retrieve` or an earlier ``ETag`` header), an
195
+ unchanged picture gives a result with ``status_code == 304`` and an empty body instead of the bytes.
196
+
197
+ An account without a picture raises :class:`~devupai.NotFoundError` (code ``avatar_not_found``).
198
+
199
+ Example::
200
+
201
+ async with await client.me.avatar() as avatar:
202
+ data = await avatar.read()
203
+ etag = avatar.headers.get("etag")
204
+ """
205
+ response = await self.with_response.avatar(
206
+ if_none_match=if_none_match, extra_headers=extra_headers, timeout=timeout, max_retries=max_retries
207
+ )
208
+ return response.data