elfa-sdk 3.0.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,421 @@
1
+ """Auto condition engine clients (`/v2/auto/*`), sync and async.
2
+
3
+ Mutations are HMAC-signed when an ``hmac_secret`` is configured (required for
4
+ trade-action queries and all exchange writes; harmless for notification-only
5
+ queries). Notification streams are exposed as generators over SSE.
6
+ """
7
+
8
+ from typing import Any, AsyncIterator, Dict, Iterator, Optional
9
+ from urllib.parse import quote
10
+
11
+ from elfa.client.base import SignedClient, drop_none, parse_model, stream_event
12
+ from elfa.exceptions import ElfaValidationError
13
+ from elfa.models.auto import (
14
+ AutoChatResponse,
15
+ AutoConvertDraftResponse,
16
+ AutoDraft,
17
+ AutoExchangeConnection,
18
+ AutoExecution,
19
+ AutoListDraftsResponse,
20
+ AutoListExchangesResponse,
21
+ AutoListExecutionsResponse,
22
+ AutoListQueriesResponse,
23
+ AutoListSessionsResponse,
24
+ AutoPollQueryResponse,
25
+ AutoQuery,
26
+ AutoSession,
27
+ AutoSpeed,
28
+ AutoStreamEvent,
29
+ AutoSuccessResponse,
30
+ AutoValidateResponse,
31
+ AutoValidateSymbolResponse,
32
+ TradableExchange,
33
+ )
34
+ from elfa.utils.http import DEFAULT_BASE_URL, AsyncTransport, SyncTransport
35
+ from elfa.utils.sse import aiter_sse, iter_sse
36
+
37
+ MOUNT = "/v2/auto"
38
+ _SSE_HEADERS = {"Accept": "text/event-stream"}
39
+
40
+
41
+ class AutoClient(SignedClient):
42
+ """Synchronous Auto engine client. Access via ``ElfaClient.auto``,
43
+ or construct standalone with an ``api_key``."""
44
+
45
+ def __init__(
46
+ self,
47
+ api_key: Optional[str] = None,
48
+ *,
49
+ base_url: str = DEFAULT_BASE_URL,
50
+ timeout: float = 30.0,
51
+ retries: int = 3,
52
+ retry_delay: float = 1.0,
53
+ hmac_secret: Optional[str] = None,
54
+ headers: Optional[Dict[str, str]] = None,
55
+ transport: Optional[SyncTransport] = None,
56
+ ):
57
+ self._owns_transport = transport is None
58
+ if transport is None:
59
+ if not api_key:
60
+ raise ElfaValidationError("api_key is required")
61
+ transport = SyncTransport(
62
+ api_key, base_url, timeout, retries, retry_delay, headers
63
+ )
64
+ super().__init__(transport, MOUNT, hmac_secret)
65
+
66
+ def close(self) -> None:
67
+ """Close the connection pool if this client owns it (standalone use)."""
68
+ if self._owns_transport:
69
+ self._transport.close()
70
+
71
+ def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
72
+ return self._transport.request_json("GET", f"{MOUNT}{path}", params=params)
73
+
74
+ def _post(self, path: str, body: Any = None) -> Any:
75
+ url, content, headers = self._post_args(path, body)
76
+ return self._transport.request_json(
77
+ "POST", url, content=content, headers=headers
78
+ )
79
+
80
+ def _delete(self, path: str) -> Any:
81
+ url, headers = self._delete_args(path)
82
+ return self._transport.request_json("DELETE", url, headers=headers)
83
+
84
+ def chat(
85
+ self,
86
+ message: str,
87
+ *,
88
+ speed: Optional[AutoSpeed] = None,
89
+ session_id: Optional[str] = None,
90
+ ) -> AutoChatResponse:
91
+ body = drop_none({"message": message, "speed": speed, "sessionId": session_id})
92
+ return parse_model(AutoChatResponse, self._post("/chat", body))
93
+
94
+ def validate_query(self, query_input: Dict[str, Any]) -> AutoValidateResponse:
95
+ return parse_model(
96
+ AutoValidateResponse, self._post("/queries/validate", query_input)
97
+ )
98
+
99
+ def create_query(self, query_input: Dict[str, Any]) -> AutoQuery:
100
+ return parse_model(AutoQuery, self._post("/queries", query_input))
101
+
102
+ def list_queries(
103
+ self,
104
+ *,
105
+ status: Optional[str] = None,
106
+ search: Optional[str] = None,
107
+ limit: Optional[int] = None,
108
+ offset: Optional[int] = None,
109
+ ) -> AutoListQueriesResponse:
110
+ params = drop_none(
111
+ {"status": status, "search": search, "limit": limit, "offset": offset}
112
+ )
113
+ return parse_model(AutoListQueriesResponse, self._get("/queries", params))
114
+
115
+ def get_query(self, query_id: str) -> AutoPollQueryResponse:
116
+ return parse_model(AutoPollQueryResponse, self._get(f"/queries/{query_id}"))
117
+
118
+ def cancel_query(self, query_id: str) -> AutoQuery:
119
+ return parse_model(AutoQuery, self._post(f"/queries/{query_id}/cancel"))
120
+
121
+ def delete_query(self, query_id: str) -> AutoQuery:
122
+ return parse_model(AutoQuery, self._delete(f"/queries/{query_id}"))
123
+
124
+ def list_drafts(
125
+ self,
126
+ *,
127
+ status: Optional[str] = None,
128
+ search: Optional[str] = None,
129
+ limit: Optional[int] = None,
130
+ offset: Optional[int] = None,
131
+ ) -> AutoListDraftsResponse:
132
+ params = drop_none(
133
+ {"status": status, "search": search, "limit": limit, "offset": offset}
134
+ )
135
+ return parse_model(AutoListDraftsResponse, self._get("/queries/drafts", params))
136
+
137
+ def get_draft(self, draft_id: str) -> AutoDraft:
138
+ return parse_model(AutoDraft, self._get(f"/queries/drafts/{draft_id}"))
139
+
140
+ def upsert_draft(self, draft_input: Dict[str, Any]) -> AutoDraft:
141
+ return parse_model(AutoDraft, self._post("/queries/drafts", draft_input))
142
+
143
+ def delete_draft(self, draft_id: str) -> Any:
144
+ return self._delete(f"/queries/drafts/{draft_id}")
145
+
146
+ def validate_draft(self, draft_id: str) -> AutoValidateResponse:
147
+ return parse_model(
148
+ AutoValidateResponse, self._post(f"/queries/drafts/{draft_id}/validate")
149
+ )
150
+
151
+ def convert_draft(self, draft_id: str) -> AutoConvertDraftResponse:
152
+ return parse_model(
153
+ AutoConvertDraftResponse,
154
+ self._post(f"/queries/drafts/{draft_id}/convert"),
155
+ )
156
+
157
+ def list_sessions(self, query_id: str) -> AutoListSessionsResponse:
158
+ return parse_model(
159
+ AutoListSessionsResponse, self._get(f"/queries/{query_id}/sessions")
160
+ )
161
+
162
+ def get_session(self, query_id: str, session_id: str) -> AutoSession:
163
+ return parse_model(
164
+ AutoSession, self._get(f"/queries/{query_id}/sessions/{session_id}")
165
+ )
166
+
167
+ def list_executions(
168
+ self,
169
+ *,
170
+ query_id: Optional[str] = None,
171
+ status: Optional[str] = None,
172
+ execution_type: Optional[str] = None,
173
+ limit: Optional[int] = None,
174
+ offset: Optional[int] = None,
175
+ ) -> AutoListExecutionsResponse:
176
+ params = drop_none(
177
+ {
178
+ "queryId": query_id,
179
+ "status": status,
180
+ "type": execution_type,
181
+ "limit": limit,
182
+ "offset": offset,
183
+ }
184
+ )
185
+ return parse_model(AutoListExecutionsResponse, self._get("/executions", params))
186
+
187
+ def get_execution(self, execution_id: str) -> AutoExecution:
188
+ return parse_model(AutoExecution, self._get(f"/executions/{execution_id}"))
189
+
190
+ def list_exchanges(self) -> AutoListExchangesResponse:
191
+ return parse_model(AutoListExchangesResponse, self._get("/exchanges"))
192
+
193
+ def connect_exchange(
194
+ self, exchange_input: Dict[str, Any]
195
+ ) -> AutoExchangeConnection:
196
+ return parse_model(
197
+ AutoExchangeConnection, self._post("/exchanges", exchange_input)
198
+ )
199
+
200
+ def disconnect_exchange(self, exchange: TradableExchange) -> AutoSuccessResponse:
201
+ return parse_model(AutoSuccessResponse, self._delete(f"/exchanges/{exchange}"))
202
+
203
+ def validate_symbol(
204
+ self, exchange: TradableExchange, symbol: str
205
+ ) -> AutoValidateSymbolResponse:
206
+ path = f"/validate-symbol/{exchange}/{quote(symbol, safe='')}"
207
+ return parse_model(AutoValidateSymbolResponse, self._get(path))
208
+
209
+ def stream_query(self, query_id: str) -> Iterator[AutoStreamEvent]:
210
+ return self._stream(f"/queries/{query_id}/stream")
211
+
212
+ def stream_all(self) -> Iterator[AutoStreamEvent]:
213
+ return self._stream("/queries/stream")
214
+
215
+ def _stream(self, path: str) -> Iterator[AutoStreamEvent]:
216
+ with self._transport.stream_lines(
217
+ "GET", f"{MOUNT}{path}", headers=_SSE_HEADERS
218
+ ) as lines:
219
+ for message in iter_sse(lines):
220
+ yield stream_event(message)
221
+ if message.event == "end":
222
+ return
223
+
224
+
225
+ class AsyncAutoClient(SignedClient):
226
+ """Asynchronous Auto engine client. Access via ``AsyncElfaClient.auto``,
227
+ or construct standalone with an ``api_key``."""
228
+
229
+ def __init__(
230
+ self,
231
+ api_key: Optional[str] = None,
232
+ *,
233
+ base_url: str = DEFAULT_BASE_URL,
234
+ timeout: float = 30.0,
235
+ retries: int = 3,
236
+ retry_delay: float = 1.0,
237
+ hmac_secret: Optional[str] = None,
238
+ headers: Optional[Dict[str, str]] = None,
239
+ transport: Optional[AsyncTransport] = None,
240
+ ):
241
+ self._owns_transport = transport is None
242
+ if transport is None:
243
+ if not api_key:
244
+ raise ElfaValidationError("api_key is required")
245
+ transport = AsyncTransport(
246
+ api_key, base_url, timeout, retries, retry_delay, headers
247
+ )
248
+ super().__init__(transport, MOUNT, hmac_secret)
249
+
250
+ async def close(self) -> None:
251
+ """Close the connection pool if this client owns it (standalone use)."""
252
+ if self._owns_transport:
253
+ await self._transport.close()
254
+
255
+ async def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
256
+ return await self._transport.request_json(
257
+ "GET", f"{MOUNT}{path}", params=params
258
+ )
259
+
260
+ async def _post(self, path: str, body: Any = None) -> Any:
261
+ url, content, headers = self._post_args(path, body)
262
+ return await self._transport.request_json(
263
+ "POST", url, content=content, headers=headers
264
+ )
265
+
266
+ async def _delete(self, path: str) -> Any:
267
+ url, headers = self._delete_args(path)
268
+ return await self._transport.request_json("DELETE", url, headers=headers)
269
+
270
+ async def chat(
271
+ self,
272
+ message: str,
273
+ *,
274
+ speed: Optional[AutoSpeed] = None,
275
+ session_id: Optional[str] = None,
276
+ ) -> AutoChatResponse:
277
+ body = drop_none({"message": message, "speed": speed, "sessionId": session_id})
278
+ return parse_model(AutoChatResponse, await self._post("/chat", body))
279
+
280
+ async def validate_query(self, query_input: Dict[str, Any]) -> AutoValidateResponse:
281
+ return parse_model(
282
+ AutoValidateResponse, await self._post("/queries/validate", query_input)
283
+ )
284
+
285
+ async def create_query(self, query_input: Dict[str, Any]) -> AutoQuery:
286
+ return parse_model(AutoQuery, await self._post("/queries", query_input))
287
+
288
+ async def list_queries(
289
+ self,
290
+ *,
291
+ status: Optional[str] = None,
292
+ search: Optional[str] = None,
293
+ limit: Optional[int] = None,
294
+ offset: Optional[int] = None,
295
+ ) -> AutoListQueriesResponse:
296
+ params = drop_none(
297
+ {"status": status, "search": search, "limit": limit, "offset": offset}
298
+ )
299
+ return parse_model(AutoListQueriesResponse, await self._get("/queries", params))
300
+
301
+ async def get_query(self, query_id: str) -> AutoPollQueryResponse:
302
+ return parse_model(
303
+ AutoPollQueryResponse, await self._get(f"/queries/{query_id}")
304
+ )
305
+
306
+ async def cancel_query(self, query_id: str) -> AutoQuery:
307
+ return parse_model(AutoQuery, await self._post(f"/queries/{query_id}/cancel"))
308
+
309
+ async def delete_query(self, query_id: str) -> AutoQuery:
310
+ return parse_model(AutoQuery, await self._delete(f"/queries/{query_id}"))
311
+
312
+ async def list_drafts(
313
+ self,
314
+ *,
315
+ status: Optional[str] = None,
316
+ search: Optional[str] = None,
317
+ limit: Optional[int] = None,
318
+ offset: Optional[int] = None,
319
+ ) -> AutoListDraftsResponse:
320
+ params = drop_none(
321
+ {"status": status, "search": search, "limit": limit, "offset": offset}
322
+ )
323
+ return parse_model(
324
+ AutoListDraftsResponse, await self._get("/queries/drafts", params)
325
+ )
326
+
327
+ async def get_draft(self, draft_id: str) -> AutoDraft:
328
+ return parse_model(AutoDraft, await self._get(f"/queries/drafts/{draft_id}"))
329
+
330
+ async def upsert_draft(self, draft_input: Dict[str, Any]) -> AutoDraft:
331
+ return parse_model(AutoDraft, await self._post("/queries/drafts", draft_input))
332
+
333
+ async def delete_draft(self, draft_id: str) -> Any:
334
+ return await self._delete(f"/queries/drafts/{draft_id}")
335
+
336
+ async def validate_draft(self, draft_id: str) -> AutoValidateResponse:
337
+ return parse_model(
338
+ AutoValidateResponse,
339
+ await self._post(f"/queries/drafts/{draft_id}/validate"),
340
+ )
341
+
342
+ async def convert_draft(self, draft_id: str) -> AutoConvertDraftResponse:
343
+ return parse_model(
344
+ AutoConvertDraftResponse,
345
+ await self._post(f"/queries/drafts/{draft_id}/convert"),
346
+ )
347
+
348
+ async def list_sessions(self, query_id: str) -> AutoListSessionsResponse:
349
+ return parse_model(
350
+ AutoListSessionsResponse, await self._get(f"/queries/{query_id}/sessions")
351
+ )
352
+
353
+ async def get_session(self, query_id: str, session_id: str) -> AutoSession:
354
+ return parse_model(
355
+ AutoSession, await self._get(f"/queries/{query_id}/sessions/{session_id}")
356
+ )
357
+
358
+ async def list_executions(
359
+ self,
360
+ *,
361
+ query_id: Optional[str] = None,
362
+ status: Optional[str] = None,
363
+ execution_type: Optional[str] = None,
364
+ limit: Optional[int] = None,
365
+ offset: Optional[int] = None,
366
+ ) -> AutoListExecutionsResponse:
367
+ params = drop_none(
368
+ {
369
+ "queryId": query_id,
370
+ "status": status,
371
+ "type": execution_type,
372
+ "limit": limit,
373
+ "offset": offset,
374
+ }
375
+ )
376
+ return parse_model(
377
+ AutoListExecutionsResponse, await self._get("/executions", params)
378
+ )
379
+
380
+ async def get_execution(self, execution_id: str) -> AutoExecution:
381
+ return parse_model(
382
+ AutoExecution, await self._get(f"/executions/{execution_id}")
383
+ )
384
+
385
+ async def list_exchanges(self) -> AutoListExchangesResponse:
386
+ return parse_model(AutoListExchangesResponse, await self._get("/exchanges"))
387
+
388
+ async def connect_exchange(
389
+ self, exchange_input: Dict[str, Any]
390
+ ) -> AutoExchangeConnection:
391
+ return parse_model(
392
+ AutoExchangeConnection, await self._post("/exchanges", exchange_input)
393
+ )
394
+
395
+ async def disconnect_exchange(
396
+ self, exchange: TradableExchange
397
+ ) -> AutoSuccessResponse:
398
+ return parse_model(
399
+ AutoSuccessResponse, await self._delete(f"/exchanges/{exchange}")
400
+ )
401
+
402
+ async def validate_symbol(
403
+ self, exchange: TradableExchange, symbol: str
404
+ ) -> AutoValidateSymbolResponse:
405
+ path = f"/validate-symbol/{exchange}/{quote(symbol, safe='')}"
406
+ return parse_model(AutoValidateSymbolResponse, await self._get(path))
407
+
408
+ def stream_query(self, query_id: str) -> AsyncIterator[AutoStreamEvent]:
409
+ return self._stream(f"/queries/{query_id}/stream")
410
+
411
+ def stream_all(self) -> AsyncIterator[AutoStreamEvent]:
412
+ return self._stream("/queries/stream")
413
+
414
+ async def _stream(self, path: str) -> AsyncIterator[AutoStreamEvent]:
415
+ async with self._transport.stream_lines(
416
+ "GET", f"{MOUNT}{path}", headers=_SSE_HEADERS
417
+ ) as lines:
418
+ async for message in aiter_sse(lines):
419
+ yield stream_event(message)
420
+ if message.event == "end":
421
+ return
elfa/client/base.py ADDED
@@ -0,0 +1,64 @@
1
+ """Shared helpers for the SDK clients."""
2
+
3
+ import json
4
+ from typing import Any, Dict, Optional, Tuple, Type, TypeVar
5
+
6
+ from pydantic import BaseModel, ValidationError
7
+
8
+ from elfa.exceptions import ElfaAPIError
9
+ from elfa.models.auto import AutoStreamEvent
10
+ from elfa.utils.hmac import sign_request
11
+ from elfa.utils.serialize import to_compact_json
12
+ from elfa.utils.sse import SSEMessage
13
+
14
+ TModel = TypeVar("TModel", bound=BaseModel)
15
+
16
+
17
+ def parse_model(model: Type[TModel], data: Any) -> TModel:
18
+ try:
19
+ return model.model_validate(data)
20
+ except ValidationError as error:
21
+ raise ElfaAPIError(f"Invalid response format: {error}")
22
+
23
+
24
+ def drop_none(params: Dict[str, Any]) -> Dict[str, Any]:
25
+ return {key: value for key, value in params.items() if value is not None}
26
+
27
+
28
+ def stream_event(message: SSEMessage) -> AutoStreamEvent:
29
+ try:
30
+ data = json.loads(message.data) if message.data else {}
31
+ except json.JSONDecodeError:
32
+ data = {"raw": message.data}
33
+ return AutoStreamEvent(event=message.event, data=data, id=message.id)
34
+
35
+
36
+ class SignedClient:
37
+ """Base for routers whose mutations are HMAC-signed (Auto, Trade).
38
+
39
+ ``_post_args`` / ``_delete_args`` build the compact-JSON body and signature
40
+ headers; the sync and async subclasses only differ in how they call the
41
+ transport with those values.
42
+ """
43
+
44
+ def __init__(self, transport: Any, mount: str, hmac_secret: Optional[str] = None):
45
+ self._transport = transport
46
+ self._mount = mount
47
+ self._hmac_secret = hmac_secret
48
+
49
+ def _sign(self, method: str, path: str, body: str) -> Optional[Dict[str, str]]:
50
+ if not self._hmac_secret:
51
+ return None
52
+ return sign_request(self._hmac_secret, method, path, body)
53
+
54
+ def _post_args(
55
+ self, path: str, body: Any = None
56
+ ) -> Tuple[str, Optional[str], Optional[Dict[str, str]]]:
57
+ body_str = "" if body is None else to_compact_json(body)
58
+ headers = self._sign("POST", path, body_str)
59
+ content = None if body is None else body_str
60
+ return f"{self._mount}{path}", content, headers
61
+
62
+ def _delete_args(self, path: str) -> Tuple[str, Optional[Dict[str, str]]]:
63
+ headers = self._sign("DELETE", path, "")
64
+ return f"{self._mount}{path}", headers