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.
- jelly_sdk-1.0.8/LICENSE +21 -0
- jelly_sdk-1.0.8/PKG-INFO +288 -0
- jelly_sdk-1.0.8/README.md +245 -0
- jelly_sdk-1.0.8/jelly_sdk/__init__.py +55 -0
- jelly_sdk-1.0.8/jelly_sdk/core/__init__.py +23 -0
- jelly_sdk-1.0.8/jelly_sdk/core/auth.py +298 -0
- jelly_sdk-1.0.8/jelly_sdk/core/config.py +118 -0
- jelly_sdk-1.0.8/jelly_sdk/core/device.py +151 -0
- jelly_sdk-1.0.8/jelly_sdk/core/exceptions.py +52 -0
- jelly_sdk-1.0.8/jelly_sdk/core/http_client.py +287 -0
- jelly_sdk-1.0.8/jelly_sdk/knowledge_base/__init__.py +15 -0
- jelly_sdk-1.0.8/jelly_sdk/knowledge_base/client.py +301 -0
- jelly_sdk-1.0.8/jelly_sdk/knowledge_base/models.py +83 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/__init__.py +17 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/_gateway.py +148 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/client.py +328 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/intelligence.py +138 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/local_store.py +160 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/models.py +153 -0
- jelly_sdk-1.0.8/jelly_sdk/memory/sync_client.py +82 -0
- jelly_sdk-1.0.8/jelly_sdk/py.typed +0 -0
- jelly_sdk-1.0.8/jelly_sdk/search/__init__.py +14 -0
- jelly_sdk-1.0.8/jelly_sdk/search/client.py +284 -0
- jelly_sdk-1.0.8/jelly_sdk/search/models.py +79 -0
- jelly_sdk-1.0.8/jelly_sdk/search/sync_client.py +90 -0
- jelly_sdk-1.0.8/jelly_sdk.egg-info/PKG-INFO +288 -0
- jelly_sdk-1.0.8/jelly_sdk.egg-info/SOURCES.txt +31 -0
- jelly_sdk-1.0.8/jelly_sdk.egg-info/dependency_links.txt +1 -0
- jelly_sdk-1.0.8/jelly_sdk.egg-info/requires.txt +23 -0
- jelly_sdk-1.0.8/jelly_sdk.egg-info/top_level.txt +1 -0
- jelly_sdk-1.0.8/pyproject.toml +68 -0
- jelly_sdk-1.0.8/setup.cfg +4 -0
- jelly_sdk-1.0.8/tests/test_compat.py +64 -0
jelly_sdk-1.0.8/LICENSE
ADDED
|
@@ -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.
|
jelly_sdk-1.0.8/PKG-INFO
ADDED
|
@@ -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
|
+
]
|