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.
elfa/__init__.py ADDED
@@ -0,0 +1,41 @@
1
+ """
2
+ Elfa AI Python SDK
3
+
4
+ Official Python SDK for the Elfa API — social intelligence, AI chat, and the
5
+ Auto/Trade engines for crypto.
6
+ """
7
+
8
+ from elfa.client.async_client import AsyncElfaClient
9
+ from elfa.client.auto_client import AsyncAutoClient, AutoClient
10
+ from elfa.client.elfa_client import ElfaClient
11
+ from elfa.client.trade_client import AsyncTradeClient, TradeClient
12
+ from elfa.exceptions import (
13
+ ElfaAPIError,
14
+ ElfaAuthenticationError,
15
+ ElfaNetworkError,
16
+ ElfaNotFoundError,
17
+ ElfaRateLimitError,
18
+ ElfaTimeoutError,
19
+ ElfaValidationError,
20
+ )
21
+ from elfa.version import VERSION as __version__
22
+
23
+ __author__ = "Elfa AI"
24
+ __email__ = "support@elfa.ai"
25
+
26
+ __all__ = [
27
+ "ElfaClient",
28
+ "AsyncElfaClient",
29
+ "AutoClient",
30
+ "AsyncAutoClient",
31
+ "TradeClient",
32
+ "AsyncTradeClient",
33
+ "ElfaAPIError",
34
+ "ElfaAuthenticationError",
35
+ "ElfaRateLimitError",
36
+ "ElfaNotFoundError",
37
+ "ElfaValidationError",
38
+ "ElfaNetworkError",
39
+ "ElfaTimeoutError",
40
+ "__version__",
41
+ ]
@@ -0,0 +1,15 @@
1
+ """Elfa SDK client classes."""
2
+
3
+ from elfa.client.async_client import AsyncElfaClient
4
+ from elfa.client.auto_client import AsyncAutoClient, AutoClient
5
+ from elfa.client.elfa_client import ElfaClient
6
+ from elfa.client.trade_client import AsyncTradeClient, TradeClient
7
+
8
+ __all__ = [
9
+ "ElfaClient",
10
+ "AsyncElfaClient",
11
+ "AutoClient",
12
+ "AsyncAutoClient",
13
+ "TradeClient",
14
+ "AsyncTradeClient",
15
+ ]
elfa/client/_params.py ADDED
@@ -0,0 +1,202 @@
1
+ """Pure request builders for the data endpoints.
2
+
3
+ Each returns ``(path, query)`` or ``(path, body)`` so the sync and async clients
4
+ share one source of truth for URL/param mapping and client-side validation.
5
+ """
6
+
7
+ from typing import Any, Dict, Mapping, Optional, Tuple
8
+
9
+ from elfa.client.base import drop_none
10
+ from elfa.exceptions import ElfaValidationError
11
+
12
+ Query = Tuple[str, Dict[str, Any]]
13
+
14
+
15
+ def _require_window_or_range(
16
+ time_window: Optional[str], from_time: Optional[int], to_time: Optional[int]
17
+ ) -> None:
18
+ has_from = from_time is not None
19
+ has_to = to_time is not None
20
+ if has_from != has_to:
21
+ raise ElfaValidationError("When using from_time/to_time, both must be provided")
22
+ if not time_window and not (has_from and has_to):
23
+ raise ElfaValidationError(
24
+ "You must provide either time_window or both from_time and to_time"
25
+ )
26
+
27
+
28
+ def trending_tokens(
29
+ time_window: Optional[str],
30
+ from_time: Optional[int],
31
+ to_time: Optional[int],
32
+ page: Optional[int],
33
+ page_size: Optional[int],
34
+ min_mentions: Optional[int],
35
+ ) -> Query:
36
+ _require_window_or_range(time_window, from_time, to_time)
37
+ return "/v2/aggregations/trending-tokens", drop_none(
38
+ {
39
+ "timeWindow": time_window,
40
+ "from": from_time,
41
+ "to": to_time,
42
+ "page": page,
43
+ "pageSize": page_size,
44
+ "minMentions": min_mentions,
45
+ }
46
+ )
47
+
48
+
49
+ def account_smart_stats(username: str) -> Query:
50
+ if not username:
51
+ raise ElfaValidationError("username is required")
52
+ return "/v2/account/smart-stats", {"username": username}
53
+
54
+
55
+ def keyword_mentions(
56
+ keywords: Optional[str],
57
+ account_name: Optional[str],
58
+ time_window: Optional[str],
59
+ from_time: Optional[int],
60
+ to_time: Optional[int],
61
+ limit: Optional[int],
62
+ search_type: Optional[str],
63
+ cursor: Optional[str],
64
+ reposts: Optional[bool],
65
+ ) -> Query:
66
+ if not keywords and not account_name:
67
+ raise ElfaValidationError("Either keywords or account_name must be provided")
68
+ return "/v2/data/keyword-mentions", drop_none(
69
+ {
70
+ "keywords": keywords,
71
+ "accountName": account_name,
72
+ "timeWindow": time_window,
73
+ "from": from_time,
74
+ "to": to_time,
75
+ "limit": limit,
76
+ "searchType": search_type,
77
+ "cursor": cursor,
78
+ "reposts": reposts,
79
+ }
80
+ )
81
+
82
+
83
+ def token_news(
84
+ time_window: Optional[str],
85
+ from_time: Optional[int],
86
+ to_time: Optional[int],
87
+ page: Optional[int],
88
+ page_size: Optional[int],
89
+ coin_ids: Optional[str],
90
+ reposts: Optional[bool],
91
+ ) -> Query:
92
+ return "/v2/data/token-news", drop_none(
93
+ {
94
+ "timeWindow": time_window,
95
+ "from": from_time,
96
+ "to": to_time,
97
+ "page": page,
98
+ "pageSize": page_size,
99
+ "coinIds": coin_ids,
100
+ "reposts": reposts,
101
+ }
102
+ )
103
+
104
+
105
+ def trending_cas(
106
+ platform: str,
107
+ time_window: Optional[str],
108
+ from_time: Optional[int],
109
+ to_time: Optional[int],
110
+ page: Optional[int],
111
+ page_size: Optional[int],
112
+ min_mentions: Optional[int],
113
+ ) -> Query:
114
+ _require_window_or_range(time_window, from_time, to_time)
115
+ return f"/v2/aggregations/trending-cas/{platform}", drop_none(
116
+ {
117
+ "timeWindow": time_window,
118
+ "from": from_time,
119
+ "to": to_time,
120
+ "page": page,
121
+ "pageSize": page_size,
122
+ "minMentions": min_mentions,
123
+ }
124
+ )
125
+
126
+
127
+ def top_mentions(
128
+ ticker: str,
129
+ time_window: Optional[str],
130
+ from_time: Optional[int],
131
+ to_time: Optional[int],
132
+ page: Optional[int],
133
+ page_size: Optional[int],
134
+ reposts: Optional[bool],
135
+ ) -> Query:
136
+ if not ticker:
137
+ raise ElfaValidationError("ticker is required")
138
+ return "/v2/data/top-mentions", drop_none(
139
+ {
140
+ "ticker": ticker,
141
+ "timeWindow": time_window,
142
+ "from": from_time,
143
+ "to": to_time,
144
+ "page": page,
145
+ "pageSize": page_size,
146
+ "reposts": reposts,
147
+ }
148
+ )
149
+
150
+
151
+ def event_summary(
152
+ keywords: str,
153
+ from_time: Optional[int],
154
+ to_time: Optional[int],
155
+ time_window: Optional[str],
156
+ search_type: Optional[str],
157
+ ) -> Query:
158
+ if not keywords:
159
+ raise ElfaValidationError("keywords is required")
160
+ return "/v2/data/event-summary", drop_none(
161
+ {
162
+ "keywords": keywords,
163
+ "from": from_time,
164
+ "to": to_time,
165
+ "timeWindow": time_window,
166
+ "searchType": search_type,
167
+ }
168
+ )
169
+
170
+
171
+ def trending_narratives(
172
+ time_frame: Optional[str],
173
+ max_narratives: Optional[int],
174
+ max_tweets_per_narrative: Optional[int],
175
+ ) -> Query:
176
+ return "/v2/data/trending-narratives", drop_none(
177
+ {
178
+ "timeFrame": time_frame,
179
+ "maxNarratives": max_narratives,
180
+ "maxTweetsPerNarrative": max_tweets_per_narrative,
181
+ }
182
+ )
183
+
184
+
185
+ def chat_body(
186
+ message: Optional[str],
187
+ session_id: Optional[str],
188
+ analysis_type: Optional[str],
189
+ speed: Optional[str],
190
+ asset_metadata: Optional[Mapping[str, Any]],
191
+ ) -> Dict[str, Any]:
192
+ if (analysis_type or "chat") == "chat" and not (message and message.strip()):
193
+ raise ElfaValidationError("message is required for chat analysis")
194
+ return drop_none(
195
+ {
196
+ "message": message,
197
+ "sessionId": session_id,
198
+ "analysisType": analysis_type,
199
+ "speed": speed,
200
+ "assetMetadata": asset_metadata,
201
+ }
202
+ )
@@ -0,0 +1,240 @@
1
+ """Asynchronous Elfa client: core data + AI chat, with ``.auto`` and ``.trade``."""
2
+
3
+ from typing import Any, Dict, Optional
4
+
5
+ from elfa.client import _params as build
6
+ from elfa.client.auto_client import AsyncAutoClient
7
+ from elfa.client.base import parse_model
8
+ from elfa.client.trade_client import AsyncTradeClient
9
+ from elfa.exceptions import ElfaAPIError, ElfaValidationError
10
+ from elfa.models.chat import (
11
+ ChatAnalysisType,
12
+ ChatAssetMetadata,
13
+ ChatResponse,
14
+ ChatSpeed,
15
+ )
16
+ from elfa.models.elfa import (
17
+ AccountSmartStatsResponse,
18
+ ApiKeyStatusResponse,
19
+ EventSummaryV2Response,
20
+ KeywordMentionsV2Response,
21
+ PingResponse,
22
+ TokenNewsV2Response,
23
+ TopMentionsV2Response,
24
+ TrendingCAsV2Response,
25
+ TrendingNarrativesResponse,
26
+ TrendingTokensResponse,
27
+ )
28
+ from elfa.utils.http import DEFAULT_BASE_URL, AsyncTransport
29
+ from elfa.utils.serialize import to_compact_json
30
+
31
+
32
+ class AsyncElfaClient:
33
+ """Asynchronous client for the Elfa API. Mirrors :class:`ElfaClient`.
34
+
35
+ Example:
36
+ >>> import asyncio
37
+ >>> from elfa import AsyncElfaClient
38
+ >>> async def main():
39
+ ... async with AsyncElfaClient(api_key="your-api-key") as client:
40
+ ... stats = await client.get_account_smart_stats("elonmusk")
41
+ ... print(stats.data.smart_following_count)
42
+ >>> asyncio.run(main())
43
+ """
44
+
45
+ def __init__(
46
+ self,
47
+ api_key: str,
48
+ base_url: str = DEFAULT_BASE_URL,
49
+ timeout: float = 30.0,
50
+ retries: int = 3,
51
+ retry_delay: float = 1.0,
52
+ hmac_secret: Optional[str] = None,
53
+ headers: Optional[Dict[str, str]] = None,
54
+ ):
55
+ if not api_key:
56
+ raise ElfaValidationError("api_key is required")
57
+
58
+ self._transport = AsyncTransport(
59
+ api_key, base_url, timeout, retries, retry_delay, headers
60
+ )
61
+ self.auto = AsyncAutoClient(transport=self._transport, hmac_secret=hmac_secret)
62
+ self.trade = AsyncTradeClient(
63
+ transport=self._transport, hmac_secret=hmac_secret
64
+ )
65
+
66
+ async def __aenter__(self) -> "AsyncElfaClient":
67
+ return self
68
+
69
+ async def __aexit__(self, *_: Any) -> None:
70
+ await self.close()
71
+
72
+ async def close(self) -> None:
73
+ """Close the underlying HTTP connection pool."""
74
+ await self._transport.close()
75
+
76
+ async def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
77
+ return await self._transport.request_json("GET", path, params=params)
78
+
79
+ async def ping(self) -> PingResponse:
80
+ return parse_model(PingResponse, await self._get("/v2/ping"))
81
+
82
+ async def get_api_key_status(self) -> ApiKeyStatusResponse:
83
+ return parse_model(ApiKeyStatusResponse, await self._get("/v2/key-status"))
84
+
85
+ async def test_connection(self) -> bool:
86
+ """Return True if the API is reachable and the key is accepted."""
87
+ try:
88
+ return (await self.ping()).success is True
89
+ except ElfaAPIError:
90
+ return False
91
+
92
+ async def get_trending_tokens(
93
+ self,
94
+ *,
95
+ time_window: Optional[str] = None,
96
+ from_time: Optional[int] = None,
97
+ to_time: Optional[int] = None,
98
+ page: Optional[int] = None,
99
+ page_size: Optional[int] = None,
100
+ min_mentions: Optional[int] = None,
101
+ ) -> TrendingTokensResponse:
102
+ path, params = build.trending_tokens(
103
+ time_window, from_time, to_time, page, page_size, min_mentions
104
+ )
105
+ return parse_model(TrendingTokensResponse, await self._get(path, params))
106
+
107
+ async def get_account_smart_stats(self, username: str) -> AccountSmartStatsResponse:
108
+ path, params = build.account_smart_stats(username)
109
+ return parse_model(AccountSmartStatsResponse, await self._get(path, params))
110
+
111
+ async def get_keyword_mentions(
112
+ self,
113
+ *,
114
+ keywords: Optional[str] = None,
115
+ account_name: Optional[str] = None,
116
+ time_window: Optional[str] = None,
117
+ from_time: Optional[int] = None,
118
+ to_time: Optional[int] = None,
119
+ limit: Optional[int] = None,
120
+ search_type: Optional[str] = None,
121
+ cursor: Optional[str] = None,
122
+ reposts: Optional[bool] = None,
123
+ ) -> KeywordMentionsV2Response:
124
+ path, params = build.keyword_mentions(
125
+ keywords,
126
+ account_name,
127
+ time_window,
128
+ from_time,
129
+ to_time,
130
+ limit,
131
+ search_type,
132
+ cursor,
133
+ reposts,
134
+ )
135
+ return parse_model(KeywordMentionsV2Response, await self._get(path, params))
136
+
137
+ async def get_token_news(
138
+ self,
139
+ *,
140
+ time_window: Optional[str] = None,
141
+ from_time: Optional[int] = None,
142
+ to_time: Optional[int] = None,
143
+ page: Optional[int] = None,
144
+ page_size: Optional[int] = None,
145
+ coin_ids: Optional[str] = None,
146
+ reposts: Optional[bool] = None,
147
+ ) -> TokenNewsV2Response:
148
+ path, params = build.token_news(
149
+ time_window, from_time, to_time, page, page_size, coin_ids, reposts
150
+ )
151
+ return parse_model(TokenNewsV2Response, await self._get(path, params))
152
+
153
+ async def get_trending_cas_twitter(
154
+ self,
155
+ *,
156
+ time_window: Optional[str] = None,
157
+ from_time: Optional[int] = None,
158
+ to_time: Optional[int] = None,
159
+ page: Optional[int] = None,
160
+ page_size: Optional[int] = None,
161
+ min_mentions: Optional[int] = None,
162
+ ) -> TrendingCAsV2Response:
163
+ path, params = build.trending_cas(
164
+ "twitter", time_window, from_time, to_time, page, page_size, min_mentions
165
+ )
166
+ return parse_model(TrendingCAsV2Response, await self._get(path, params))
167
+
168
+ async def get_trending_cas_telegram(
169
+ self,
170
+ *,
171
+ time_window: Optional[str] = None,
172
+ from_time: Optional[int] = None,
173
+ to_time: Optional[int] = None,
174
+ page: Optional[int] = None,
175
+ page_size: Optional[int] = None,
176
+ min_mentions: Optional[int] = None,
177
+ ) -> TrendingCAsV2Response:
178
+ path, params = build.trending_cas(
179
+ "telegram", time_window, from_time, to_time, page, page_size, min_mentions
180
+ )
181
+ return parse_model(TrendingCAsV2Response, await self._get(path, params))
182
+
183
+ async def get_top_mentions(
184
+ self,
185
+ ticker: str,
186
+ *,
187
+ time_window: Optional[str] = None,
188
+ from_time: Optional[int] = None,
189
+ to_time: Optional[int] = None,
190
+ page: Optional[int] = None,
191
+ page_size: Optional[int] = None,
192
+ reposts: Optional[bool] = None,
193
+ ) -> TopMentionsV2Response:
194
+ path, params = build.top_mentions(
195
+ ticker, time_window, from_time, to_time, page, page_size, reposts
196
+ )
197
+ return parse_model(TopMentionsV2Response, await self._get(path, params))
198
+
199
+ async def get_event_summary(
200
+ self,
201
+ keywords: str,
202
+ *,
203
+ from_time: Optional[int] = None,
204
+ to_time: Optional[int] = None,
205
+ time_window: Optional[str] = None,
206
+ search_type: Optional[str] = None,
207
+ ) -> EventSummaryV2Response:
208
+ path, params = build.event_summary(
209
+ keywords, from_time, to_time, time_window, search_type
210
+ )
211
+ return parse_model(EventSummaryV2Response, await self._get(path, params))
212
+
213
+ async def get_trending_narratives(
214
+ self,
215
+ *,
216
+ time_frame: Optional[str] = None,
217
+ max_narratives: Optional[int] = None,
218
+ max_tweets_per_narrative: Optional[int] = None,
219
+ ) -> TrendingNarrativesResponse:
220
+ path, params = build.trending_narratives(
221
+ time_frame, max_narratives, max_tweets_per_narrative
222
+ )
223
+ return parse_model(TrendingNarrativesResponse, await self._get(path, params))
224
+
225
+ async def chat(
226
+ self,
227
+ message: Optional[str] = None,
228
+ *,
229
+ session_id: Optional[str] = None,
230
+ analysis_type: Optional[ChatAnalysisType] = None,
231
+ speed: Optional[ChatSpeed] = None,
232
+ asset_metadata: Optional[ChatAssetMetadata] = None,
233
+ ) -> ChatResponse:
234
+ body = build.chat_body(
235
+ message, session_id, analysis_type, speed, asset_metadata
236
+ )
237
+ data = await self._transport.request_json(
238
+ "POST", "/v2/chat", content=to_compact_json(body)
239
+ )
240
+ return parse_model(ChatResponse, data)