jelly-sdk 1.0.8__tar.gz

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.
Files changed (33) hide show
  1. jelly_sdk-1.0.8/LICENSE +21 -0
  2. jelly_sdk-1.0.8/PKG-INFO +288 -0
  3. jelly_sdk-1.0.8/README.md +245 -0
  4. jelly_sdk-1.0.8/jelly_sdk/__init__.py +55 -0
  5. jelly_sdk-1.0.8/jelly_sdk/core/__init__.py +23 -0
  6. jelly_sdk-1.0.8/jelly_sdk/core/auth.py +298 -0
  7. jelly_sdk-1.0.8/jelly_sdk/core/config.py +118 -0
  8. jelly_sdk-1.0.8/jelly_sdk/core/device.py +151 -0
  9. jelly_sdk-1.0.8/jelly_sdk/core/exceptions.py +52 -0
  10. jelly_sdk-1.0.8/jelly_sdk/core/http_client.py +287 -0
  11. jelly_sdk-1.0.8/jelly_sdk/knowledge_base/__init__.py +15 -0
  12. jelly_sdk-1.0.8/jelly_sdk/knowledge_base/client.py +301 -0
  13. jelly_sdk-1.0.8/jelly_sdk/knowledge_base/models.py +83 -0
  14. jelly_sdk-1.0.8/jelly_sdk/memory/__init__.py +17 -0
  15. jelly_sdk-1.0.8/jelly_sdk/memory/_gateway.py +148 -0
  16. jelly_sdk-1.0.8/jelly_sdk/memory/client.py +328 -0
  17. jelly_sdk-1.0.8/jelly_sdk/memory/intelligence.py +138 -0
  18. jelly_sdk-1.0.8/jelly_sdk/memory/local_store.py +160 -0
  19. jelly_sdk-1.0.8/jelly_sdk/memory/models.py +153 -0
  20. jelly_sdk-1.0.8/jelly_sdk/memory/sync_client.py +82 -0
  21. jelly_sdk-1.0.8/jelly_sdk/py.typed +0 -0
  22. jelly_sdk-1.0.8/jelly_sdk/search/__init__.py +14 -0
  23. jelly_sdk-1.0.8/jelly_sdk/search/client.py +284 -0
  24. jelly_sdk-1.0.8/jelly_sdk/search/models.py +79 -0
  25. jelly_sdk-1.0.8/jelly_sdk/search/sync_client.py +90 -0
  26. jelly_sdk-1.0.8/jelly_sdk.egg-info/PKG-INFO +288 -0
  27. jelly_sdk-1.0.8/jelly_sdk.egg-info/SOURCES.txt +31 -0
  28. jelly_sdk-1.0.8/jelly_sdk.egg-info/dependency_links.txt +1 -0
  29. jelly_sdk-1.0.8/jelly_sdk.egg-info/requires.txt +23 -0
  30. jelly_sdk-1.0.8/jelly_sdk.egg-info/top_level.txt +1 -0
  31. jelly_sdk-1.0.8/pyproject.toml +68 -0
  32. jelly_sdk-1.0.8/setup.cfg +4 -0
  33. jelly_sdk-1.0.8/tests/test_compat.py +64 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jelly
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,288 @@
1
+ Metadata-Version: 2.4
2
+ Name: jelly-sdk
3
+ Version: 1.0.8
4
+ Summary: Jelly SDK - Search and Memory for AI Agents
5
+ Author: Jelly Team
6
+ License: MIT
7
+ Project-URL: Homepage, https://jelly.datanaan.cn
8
+ Project-URL: Documentation, https://jelly.datanaan.cn/sense
9
+ Keywords: ai-agents,search,memory,rag,mcp,knowledge-base
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: aiohttp>=3.9.0
24
+ Requires-Dist: pydantic>=2.0.0
25
+ Provides-Extra: memory
26
+ Requires-Dist: aiosqlite>=0.19.0; extra == "memory"
27
+ Requires-Dist: numpy>=1.24.0; extra == "memory"
28
+ Requires-Dist: sentence-transformers>=2.2.0; extra == "memory"
29
+ Requires-Dist: faiss-cpu>=1.7.4; extra == "memory"
30
+ Provides-Extra: memory-minimal
31
+ Requires-Dist: aiosqlite>=0.19.0; extra == "memory-minimal"
32
+ Requires-Dist: numpy>=1.24.0; extra == "memory-minimal"
33
+ Provides-Extra: all
34
+ Requires-Dist: aiosqlite>=0.19.0; extra == "all"
35
+ Requires-Dist: numpy>=1.24.0; extra == "all"
36
+ Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
37
+ Requires-Dist: faiss-cpu>=1.7.4; extra == "all"
38
+ Provides-Extra: dev
39
+ Requires-Dist: pytest>=7.0; extra == "dev"
40
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
41
+ Requires-Dist: aioresponses>=0.7; extra == "dev"
42
+ Dynamic: license-file
43
+
44
+ # jelly-sdk
45
+
46
+ Python SDK for Jelly — unified search and memory client for AI agents.
47
+
48
+ ## Installation
49
+
50
+ > ⚠️ jelly-sdk **未发布到 PyPI**(I-607①:`pip install jelly-sdk` 会装到无关包或直接失败)。
51
+ > 请从内部 Git 服务器安装:
52
+
53
+ ```bash
54
+ # Core (search only)
55
+ pip install "jelly-sdk @ git+ssh://git@172.80.1.100:2222/research/jelly-sdk.git"
56
+
57
+ # With memory support
58
+ pip install "jelly-sdk[memory] @ git+ssh://git@172.80.1.100:2222/research/jelly-sdk.git"
59
+
60
+ # With minimal memory (no sentence-transformers/FAISS)
61
+ pip install "jelly-sdk[memory_minimal] @ git+ssh://git@172.80.1.100:2222/research/jelly-sdk.git"
62
+ ```
63
+
64
+ ## Quick Start
65
+
66
+ ### Search
67
+
68
+ ```python
69
+ import asyncio
70
+ from jelly_sdk import JellySearch
71
+
72
+ async def main():
73
+ client = JellySearch() # reads JELLY_BASE_URL from env
74
+ await client.ensure_authenticated() # auto-registers if no API key
75
+
76
+ # Search — pass kb_ids explicitly (auto-routing is announced but not
77
+ # shipped yet; without kb_ids the result may be empty).
78
+ resp = await client.search(
79
+ "Go 1.27 技术现状与生态",
80
+ kb_ids=["kb_investigation_reports"],
81
+ )
82
+ # resp.results 形如 {查询串: [SearchResult, ...]}
83
+ for items in resp.results.values():
84
+ for r in items:
85
+ print(f"[{r.score:.3f}] {r.title or r.text[:60]}")
86
+
87
+ # Ask with citations
88
+ answer = await client.ask(
89
+ "Go 1.27 技术现状与生态",
90
+ kb_ids=["kb_investigation_reports"],
91
+ )
92
+ print(answer.answer)
93
+
94
+ await client.close()
95
+
96
+ asyncio.run(main())
97
+ ```
98
+
99
+ ### 同步用法(脚本/Notebook 免 asyncio)
100
+
101
+ ```python
102
+ from jelly_sdk import JellySearchSync
103
+
104
+ client = JellySearchSync() # 方法面与 JellySearch 一一对应
105
+ resp = client.search("评标委员会", kb_ids=["kb_procurement_rules"], top_k=3)
106
+ print(resp.total)
107
+ client.close()
108
+ ```
109
+
110
+ 更多可跑示例见 `examples/`(search / memory / kb serving 三脚本)。
111
+
112
+ ### Memory
113
+
114
+ > ⚠️ **服务现势(2026-11-22 实弹核验)**:jelly-memory 后端暂未开放支持(下架中)——
115
+ > Memory 面调用统一返回 `503 JELLY_1000 "Memory Service unavailable"`。
116
+ > SDK 方法面保留(服务恢复即用,无需升版);**search 面不受影响**。
117
+
118
+ ```python
119
+ import asyncio
120
+ from jelly_sdk import JellyMemory
121
+
122
+ async def main():
123
+ client = JellyMemory(mode="cloud_only")
124
+ await client.ensure_authenticated()
125
+
126
+ # Store
127
+ await client.remember("User prefers dark mode", tags=["preference"])
128
+
129
+ # Recall — resp 形如 {"success": True, "memories": [{id, content, ...}]}
130
+ resp = await client.recall("UI preferences")
131
+ for m in resp.get("memories", []):
132
+ print(m.get("content"))
133
+
134
+ await client.close()
135
+
136
+ asyncio.run(main())
137
+ ```
138
+
139
+ ## Configuration
140
+
141
+ Set environment variables or pass config directly:
142
+
143
+ | Variable | Required | Description | Default |
144
+ |----------|----------|-------------|---------|
145
+ | `JELLY_BASE_URL` | Yes | Jelly API endpoint | `http://127.0.0.1:8000` |
146
+ | `JELLY_API_KEY` | No | Pre-existing API key (skips registration) | Auto-register |
147
+ | `JELLY_TIMEOUT` | No | HTTP timeout (seconds) | 30 |
148
+
149
+ ```python
150
+ from jelly_sdk import JellySearch
151
+ from jelly_sdk.core.config import JellyConfig
152
+
153
+ # Via environment variables (recommended)
154
+ client = JellySearch() # reads from env
155
+
156
+ # Or explicit config
157
+ config = JellyConfig(base_url="https://jelly.datanaan.cn", api_key="jelly_xxx")
158
+ client = JellySearch(config=config)
159
+ ```
160
+
161
+ ### 配置与域名切换
162
+
163
+ API 地址唯一开关点 = `JELLY_BASE_URL`(或 `JellyConfig(base_url=...)`),换域名零代码改动:
164
+
165
+ ```bash
166
+ export JELLY_BASE_URL=https://jelly.datanaan.cn # 现网
167
+ # 域名迁移后(如 .com)仅需换这一行,SDK 自动对新端点重新注册
168
+ export JELLY_BASE_URL=https://jelly.datanaan.com
169
+ ```
170
+
171
+ 跨域名切换行为(I-614):`~/.jelly/api_key` 缓存记录签发域名——`JELLY_BASE_URL`
172
+ 变更后旧 key 自动判过期并**对新端点重新注册**,不会把旧域名 key 发给新域名拿 401。
173
+ 旧格式缓存(无域名字段)向后兼容原样加载。
174
+
175
+ ### Auto-Registration
176
+
177
+ When no `JELLY_API_KEY` is provided, the SDK automatically:
178
+
179
+ 1. Generates a device ID → `~/.jelly/device_id`
180
+ 2. Registers with backend → receives API key
181
+ 3. Caches the key → `~/.jelly/api_key` (JSON, 0600 permissions)
182
+
183
+ On subsequent starts, the cached key is used. To migrate, copy both `~/.jelly/device_id` and `~/.jelly/api_key`.
184
+
185
+ ## Error Handling
186
+
187
+ Exceptions propagate to callers — handle them explicitly:
188
+
189
+ ```python
190
+ from jelly_sdk import JellySearch, JellyAuthError, JellyQuotaExhaustedError
191
+
192
+ try:
193
+ results = await client.search("query")
194
+ except JellyAuthError:
195
+ print("API key invalid or expired")
196
+ except JellyQuotaExhaustedError as e:
197
+ print(f"Quota exhausted. Claim: {e.claim_url}")
198
+ print(f"Upgrade: {e.upgrade_url}")
199
+ ```
200
+
201
+ Exception hierarchy:
202
+
203
+ ```
204
+ JellyHttpError (base, carries status + message + path)
205
+ ├── JellyAuthError # 401 — invalid or expired key
206
+ ├── JellyQuotaExhaustedError # 402 — quota exhausted (has claim_url, upgrade_url)
207
+ ├── JellyRateLimitError # 429 — too many requests (has retry_after)
208
+ └── JellyConnectionError # network error
209
+ ```
210
+
211
+ ## API Reference
212
+
213
+ ### JellySearch
214
+
215
+ | Method | Description |
216
+ |--------|-------------|
217
+ | `search(query, **kwargs)` | Hybrid search |
218
+ | `ask(question, **kwargs)` | Ask with citations |
219
+ | `enhance_query(query, **kwargs)` | Enhance query for better results |
220
+ | `rerank(query, documents, **kwargs)` | Re-rank documents |
221
+ | `list_knowledge_bases()` | List available KBs |
222
+ | `get_suggestions(query, **kwargs)` | Auto-complete suggestions |
223
+ | `ensure_authenticated()` | Auto-register and get API key |
224
+ | `initiate_claim()` | Get claim code for device |
225
+ | `get_device_quota()` | Check quota usage |
226
+ | `close()` | Close HTTP session |
227
+
228
+ ### JellyMemory
229
+
230
+ | Method | Description |
231
+ |--------|-------------|
232
+ | `remember(content, **kwargs)` | Store memory |
233
+ | `recall(query, **kwargs)` | Recall memories |
234
+ | `forget(memory_id)` | Delete memory |
235
+ | `learn(content, **kwargs)` | Learn with auto type detection |
236
+ | `reflect(query, **kwargs)` | LLM synthesis |
237
+ | `dream()` | Consolidate memories — **requires ADMIN API key**; device keys get a 403 with guidance (I-608②) |
238
+ | `share(memory_id, **kwargs)` | Share with other agents |
239
+ | `discover(query, **kwargs)` | Find shared memories |
240
+ | `my_memories(**kwargs)` | List stored memories |
241
+ | `my_stats()` | Usage statistics |
242
+ | `ensure_authenticated()` | Auto-register |
243
+ | `close()` | Close HTTP session |
244
+
245
+ ### JellyKnowledgeBase(经 :8000 gateway 的 KB 代理,v0.5+)
246
+
247
+ > 25 方法(2026-11-22 与 `jelly_sdk/knowledge_base/client.py` 核对,含 v1.0.6 新增受控 serving 四原语)。经 jelly_search_v3 :8000 的 `gateway/kb/*` 代理访问 KB 引擎,非直连。旧 v0.4 `base_url=:8096` 直连参数已 deprecated。
248
+
249
+ | Method | Description |
250
+ |--------|-------------|
251
+ | `register_kb(kb_id, name, ...)` | Register a KB |
252
+ | `list_kbs()` | List KBs |
253
+ | `get_kb(kb_id)` | Get KB detail |
254
+ | `delete_kb(kb_id)` | Delete a KB |
255
+ | `delete_row(kb_id, table, row_id)` | Soft-delete a row |
256
+ | `inspect(kb_id, refresh)` | Inspect KB tables/rows/health |
257
+ | `create_with_template(kb_id, template)` | Create KB from template |
258
+ | `get_schema(kb_id)` | Get KB schema |
259
+ | `query(kb_id, sql, limit)` | SQL query |
260
+ | `time_query(kb_id, table, select_expr, ...)` | Time aggregation |
261
+ | `entity_events(kb_id, table, entity_id)` | Entity lifecycle events |
262
+ | `snapshot(kb_id, table, entity_id, at_time)` | State at point in time |
263
+ | `diff(kb_id, table, entity_id, ...)` | Diff between time points |
264
+ | `version_history(kb_id, table, entity_id)` | Version history |
265
+ | `index_document(kb_id, doc_id, ...)` | Index a document |
266
+ | `search_documents(kb_id, query, ...)` | Search indexed documents |
267
+ | `add_column(kb_id, table, name, ...)` | Add a column |
268
+ | `rename_column(kb_id, table, ...)` | Rename a column |
269
+ | `undo_import(kb_id, task_id, ...)` | Undo an import |
270
+ | `append_data(kb_id, table, rows, ...)` | Append rows |
271
+ | `cross_search(kb_id, query, ...)` | Cross-search entities |
272
+ | `records(kb_id, table, columns, ...)` | Controlled serving: filtered rows |
273
+ | `aggregate(kb_id, table, metrics, ...)` | Controlled serving: group-by aggregation |
274
+ | `entity(kb_id, query, ...)` | Five-dim entity profile (query XOR entity_id) |
275
+ | `graph(kb_id, entity_id, ...)` | Graph traversal (Neo4j star query) |
276
+
277
+ ## Requirements
278
+
279
+ - Python >= 3.10
280
+ - aiohttp >= 3.9.0
281
+ - pydantic >= 2.0.0
282
+
283
+ For memory features additionally:
284
+ - aiosqlite, numpy, sentence-transformers, faiss-cpu
285
+
286
+ ## License
287
+
288
+ MIT
@@ -0,0 +1,245 @@
1
+ # jelly-sdk
2
+
3
+ Python SDK for Jelly — unified search and memory client for AI agents.
4
+
5
+ ## Installation
6
+
7
+ > ⚠️ jelly-sdk **未发布到 PyPI**(I-607①:`pip install jelly-sdk` 会装到无关包或直接失败)。
8
+ > 请从内部 Git 服务器安装:
9
+
10
+ ```bash
11
+ # Core (search only)
12
+ pip install "jelly-sdk @ git+ssh://git@172.80.1.100:2222/research/jelly-sdk.git"
13
+
14
+ # With memory support
15
+ pip install "jelly-sdk[memory] @ git+ssh://git@172.80.1.100:2222/research/jelly-sdk.git"
16
+
17
+ # With minimal memory (no sentence-transformers/FAISS)
18
+ pip install "jelly-sdk[memory_minimal] @ git+ssh://git@172.80.1.100:2222/research/jelly-sdk.git"
19
+ ```
20
+
21
+ ## Quick Start
22
+
23
+ ### Search
24
+
25
+ ```python
26
+ import asyncio
27
+ from jelly_sdk import JellySearch
28
+
29
+ async def main():
30
+ client = JellySearch() # reads JELLY_BASE_URL from env
31
+ await client.ensure_authenticated() # auto-registers if no API key
32
+
33
+ # Search — pass kb_ids explicitly (auto-routing is announced but not
34
+ # shipped yet; without kb_ids the result may be empty).
35
+ resp = await client.search(
36
+ "Go 1.27 技术现状与生态",
37
+ kb_ids=["kb_investigation_reports"],
38
+ )
39
+ # resp.results 形如 {查询串: [SearchResult, ...]}
40
+ for items in resp.results.values():
41
+ for r in items:
42
+ print(f"[{r.score:.3f}] {r.title or r.text[:60]}")
43
+
44
+ # Ask with citations
45
+ answer = await client.ask(
46
+ "Go 1.27 技术现状与生态",
47
+ kb_ids=["kb_investigation_reports"],
48
+ )
49
+ print(answer.answer)
50
+
51
+ await client.close()
52
+
53
+ asyncio.run(main())
54
+ ```
55
+
56
+ ### 同步用法(脚本/Notebook 免 asyncio)
57
+
58
+ ```python
59
+ from jelly_sdk import JellySearchSync
60
+
61
+ client = JellySearchSync() # 方法面与 JellySearch 一一对应
62
+ resp = client.search("评标委员会", kb_ids=["kb_procurement_rules"], top_k=3)
63
+ print(resp.total)
64
+ client.close()
65
+ ```
66
+
67
+ 更多可跑示例见 `examples/`(search / memory / kb serving 三脚本)。
68
+
69
+ ### Memory
70
+
71
+ > ⚠️ **服务现势(2026-11-22 实弹核验)**:jelly-memory 后端暂未开放支持(下架中)——
72
+ > Memory 面调用统一返回 `503 JELLY_1000 "Memory Service unavailable"`。
73
+ > SDK 方法面保留(服务恢复即用,无需升版);**search 面不受影响**。
74
+
75
+ ```python
76
+ import asyncio
77
+ from jelly_sdk import JellyMemory
78
+
79
+ async def main():
80
+ client = JellyMemory(mode="cloud_only")
81
+ await client.ensure_authenticated()
82
+
83
+ # Store
84
+ await client.remember("User prefers dark mode", tags=["preference"])
85
+
86
+ # Recall — resp 形如 {"success": True, "memories": [{id, content, ...}]}
87
+ resp = await client.recall("UI preferences")
88
+ for m in resp.get("memories", []):
89
+ print(m.get("content"))
90
+
91
+ await client.close()
92
+
93
+ asyncio.run(main())
94
+ ```
95
+
96
+ ## Configuration
97
+
98
+ Set environment variables or pass config directly:
99
+
100
+ | Variable | Required | Description | Default |
101
+ |----------|----------|-------------|---------|
102
+ | `JELLY_BASE_URL` | Yes | Jelly API endpoint | `http://127.0.0.1:8000` |
103
+ | `JELLY_API_KEY` | No | Pre-existing API key (skips registration) | Auto-register |
104
+ | `JELLY_TIMEOUT` | No | HTTP timeout (seconds) | 30 |
105
+
106
+ ```python
107
+ from jelly_sdk import JellySearch
108
+ from jelly_sdk.core.config import JellyConfig
109
+
110
+ # Via environment variables (recommended)
111
+ client = JellySearch() # reads from env
112
+
113
+ # Or explicit config
114
+ config = JellyConfig(base_url="https://jelly.datanaan.cn", api_key="jelly_xxx")
115
+ client = JellySearch(config=config)
116
+ ```
117
+
118
+ ### 配置与域名切换
119
+
120
+ API 地址唯一开关点 = `JELLY_BASE_URL`(或 `JellyConfig(base_url=...)`),换域名零代码改动:
121
+
122
+ ```bash
123
+ export JELLY_BASE_URL=https://jelly.datanaan.cn # 现网
124
+ # 域名迁移后(如 .com)仅需换这一行,SDK 自动对新端点重新注册
125
+ export JELLY_BASE_URL=https://jelly.datanaan.com
126
+ ```
127
+
128
+ 跨域名切换行为(I-614):`~/.jelly/api_key` 缓存记录签发域名——`JELLY_BASE_URL`
129
+ 变更后旧 key 自动判过期并**对新端点重新注册**,不会把旧域名 key 发给新域名拿 401。
130
+ 旧格式缓存(无域名字段)向后兼容原样加载。
131
+
132
+ ### Auto-Registration
133
+
134
+ When no `JELLY_API_KEY` is provided, the SDK automatically:
135
+
136
+ 1. Generates a device ID → `~/.jelly/device_id`
137
+ 2. Registers with backend → receives API key
138
+ 3. Caches the key → `~/.jelly/api_key` (JSON, 0600 permissions)
139
+
140
+ On subsequent starts, the cached key is used. To migrate, copy both `~/.jelly/device_id` and `~/.jelly/api_key`.
141
+
142
+ ## Error Handling
143
+
144
+ Exceptions propagate to callers — handle them explicitly:
145
+
146
+ ```python
147
+ from jelly_sdk import JellySearch, JellyAuthError, JellyQuotaExhaustedError
148
+
149
+ try:
150
+ results = await client.search("query")
151
+ except JellyAuthError:
152
+ print("API key invalid or expired")
153
+ except JellyQuotaExhaustedError as e:
154
+ print(f"Quota exhausted. Claim: {e.claim_url}")
155
+ print(f"Upgrade: {e.upgrade_url}")
156
+ ```
157
+
158
+ Exception hierarchy:
159
+
160
+ ```
161
+ JellyHttpError (base, carries status + message + path)
162
+ ├── JellyAuthError # 401 — invalid or expired key
163
+ ├── JellyQuotaExhaustedError # 402 — quota exhausted (has claim_url, upgrade_url)
164
+ ├── JellyRateLimitError # 429 — too many requests (has retry_after)
165
+ └── JellyConnectionError # network error
166
+ ```
167
+
168
+ ## API Reference
169
+
170
+ ### JellySearch
171
+
172
+ | Method | Description |
173
+ |--------|-------------|
174
+ | `search(query, **kwargs)` | Hybrid search |
175
+ | `ask(question, **kwargs)` | Ask with citations |
176
+ | `enhance_query(query, **kwargs)` | Enhance query for better results |
177
+ | `rerank(query, documents, **kwargs)` | Re-rank documents |
178
+ | `list_knowledge_bases()` | List available KBs |
179
+ | `get_suggestions(query, **kwargs)` | Auto-complete suggestions |
180
+ | `ensure_authenticated()` | Auto-register and get API key |
181
+ | `initiate_claim()` | Get claim code for device |
182
+ | `get_device_quota()` | Check quota usage |
183
+ | `close()` | Close HTTP session |
184
+
185
+ ### JellyMemory
186
+
187
+ | Method | Description |
188
+ |--------|-------------|
189
+ | `remember(content, **kwargs)` | Store memory |
190
+ | `recall(query, **kwargs)` | Recall memories |
191
+ | `forget(memory_id)` | Delete memory |
192
+ | `learn(content, **kwargs)` | Learn with auto type detection |
193
+ | `reflect(query, **kwargs)` | LLM synthesis |
194
+ | `dream()` | Consolidate memories — **requires ADMIN API key**; device keys get a 403 with guidance (I-608②) |
195
+ | `share(memory_id, **kwargs)` | Share with other agents |
196
+ | `discover(query, **kwargs)` | Find shared memories |
197
+ | `my_memories(**kwargs)` | List stored memories |
198
+ | `my_stats()` | Usage statistics |
199
+ | `ensure_authenticated()` | Auto-register |
200
+ | `close()` | Close HTTP session |
201
+
202
+ ### JellyKnowledgeBase(经 :8000 gateway 的 KB 代理,v0.5+)
203
+
204
+ > 25 方法(2026-11-22 与 `jelly_sdk/knowledge_base/client.py` 核对,含 v1.0.6 新增受控 serving 四原语)。经 jelly_search_v3 :8000 的 `gateway/kb/*` 代理访问 KB 引擎,非直连。旧 v0.4 `base_url=:8096` 直连参数已 deprecated。
205
+
206
+ | Method | Description |
207
+ |--------|-------------|
208
+ | `register_kb(kb_id, name, ...)` | Register a KB |
209
+ | `list_kbs()` | List KBs |
210
+ | `get_kb(kb_id)` | Get KB detail |
211
+ | `delete_kb(kb_id)` | Delete a KB |
212
+ | `delete_row(kb_id, table, row_id)` | Soft-delete a row |
213
+ | `inspect(kb_id, refresh)` | Inspect KB tables/rows/health |
214
+ | `create_with_template(kb_id, template)` | Create KB from template |
215
+ | `get_schema(kb_id)` | Get KB schema |
216
+ | `query(kb_id, sql, limit)` | SQL query |
217
+ | `time_query(kb_id, table, select_expr, ...)` | Time aggregation |
218
+ | `entity_events(kb_id, table, entity_id)` | Entity lifecycle events |
219
+ | `snapshot(kb_id, table, entity_id, at_time)` | State at point in time |
220
+ | `diff(kb_id, table, entity_id, ...)` | Diff between time points |
221
+ | `version_history(kb_id, table, entity_id)` | Version history |
222
+ | `index_document(kb_id, doc_id, ...)` | Index a document |
223
+ | `search_documents(kb_id, query, ...)` | Search indexed documents |
224
+ | `add_column(kb_id, table, name, ...)` | Add a column |
225
+ | `rename_column(kb_id, table, ...)` | Rename a column |
226
+ | `undo_import(kb_id, task_id, ...)` | Undo an import |
227
+ | `append_data(kb_id, table, rows, ...)` | Append rows |
228
+ | `cross_search(kb_id, query, ...)` | Cross-search entities |
229
+ | `records(kb_id, table, columns, ...)` | Controlled serving: filtered rows |
230
+ | `aggregate(kb_id, table, metrics, ...)` | Controlled serving: group-by aggregation |
231
+ | `entity(kb_id, query, ...)` | Five-dim entity profile (query XOR entity_id) |
232
+ | `graph(kb_id, entity_id, ...)` | Graph traversal (Neo4j star query) |
233
+
234
+ ## Requirements
235
+
236
+ - Python >= 3.10
237
+ - aiohttp >= 3.9.0
238
+ - pydantic >= 2.0.0
239
+
240
+ For memory features additionally:
241
+ - aiosqlite, numpy, sentence-transformers, faiss-cpu
242
+
243
+ ## License
244
+
245
+ MIT
@@ -0,0 +1,55 @@
1
+ """Jelly SDK — Unified Search and Memory for AI Agents."""
2
+
3
+ # Single source of truth is pyproject.toml; read the installed dist version so
4
+ # the importable version can never drift from the published package again
5
+ # (plan-11: the 0.6.0 hardcode vs 1.0.0 pyproject mismatch is what made the
6
+ # 199 shadow install confusing to diagnose).
7
+ try:
8
+ from importlib.metadata import PackageNotFoundError, version as _dist_version
9
+
10
+ __version__ = _dist_version("jelly-sdk")
11
+ except PackageNotFoundError: # not installed (e.g. raw sys.path import from a checkout)
12
+ # I-603 纪律:此处 fallback 必须随 pyproject 升版同步改——publish.sh [2b]
13
+ # 步骤机械断言三处一致,漏改会在发布门被拦下。
14
+ __version__ = "1.0.8"
15
+
16
+ from .search import JellySearch, SearchResponse, SearchResult, AskResponse, Citation
17
+ from .core.config import JellyConfig
18
+ from .core.exceptions import (
19
+ JellyHttpError,
20
+ JellyAuthError,
21
+ JellyQuotaExhaustedError,
22
+ JellyRateLimitError,
23
+ JellyConnectionError,
24
+ )
25
+
26
+ __all__ = [
27
+ "JellySearch",
28
+ "SearchResponse",
29
+ "SearchResult",
30
+ "AskResponse",
31
+ "Citation",
32
+ "JellyConfig",
33
+ "JellyHttpError",
34
+ "JellyAuthError",
35
+ "JellyQuotaExhaustedError",
36
+ "JellyRateLimitError",
37
+ "JellyConnectionError",
38
+ ]
39
+
40
+
41
+ def __getattr__(name):
42
+ """Lazy import for optional modules (memory, knowledge_base, sync wrappers)."""
43
+ if name in ("JellyMemory", "MemoryEntry", "MemoryType", "MemoryLayer", "MemoryMode"):
44
+ from . import memory
45
+ return getattr(memory, name)
46
+ if name == "JellyMemorySync":
47
+ from .memory.sync_client import JellyMemorySync
48
+ return JellyMemorySync
49
+ if name == "JellySearchSync":
50
+ from .search.sync_client import JellySearchSync
51
+ return JellySearchSync
52
+ if name in ("JellyKnowledgeBase", "KBInfo", "CrossSearchResponse"):
53
+ from . import knowledge_base
54
+ return getattr(knowledge_base, name)
55
+ raise AttributeError(f"module 'jelly_sdk' has no attribute {name!r}")
@@ -0,0 +1,23 @@
1
+ from .config import JellyConfig
2
+ from .auth import AuthManager
3
+ from .device import DeviceManager
4
+ from .http_client import JellyHttpClient
5
+ from .exceptions import (
6
+ JellyHttpError,
7
+ JellyAuthError,
8
+ JellyQuotaExhaustedError,
9
+ JellyRateLimitError,
10
+ JellyConnectionError,
11
+ )
12
+
13
+ __all__ = [
14
+ "JellyConfig",
15
+ "AuthManager",
16
+ "DeviceManager",
17
+ "JellyHttpClient",
18
+ "JellyHttpError",
19
+ "JellyAuthError",
20
+ "JellyQuotaExhaustedError",
21
+ "JellyRateLimitError",
22
+ "JellyConnectionError",
23
+ ]