dxmt-python-sdk 1.6.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.
- dxmt/__init__.py +166 -0
- dxmt/bisheng_integration.py +226 -0
- dxmt/client.py +2510 -0
- dxmt/crewai_storage.py +524 -0
- dxmt/crewai_tool.py +430 -0
- dxmt/exceptions.py +46 -0
- dxmt/filters.py +360 -0
- dxmt/haystack.py +773 -0
- dxmt/haystack_retrievers.py +372 -0
- dxmt/langchain_vectorstore.py +527 -0
- dxmt/langgraph_store.py +1054 -0
- dxmt/mem0.py +653 -0
- dxmt/metagpt_retriever.py +361 -0
- dxmt/metagpt_vector_store.py +466 -0
- dxmt/migrate/__init__.py +1 -0
- dxmt/migrate/chroma.py +237 -0
- dxmt/py.typed +0 -0
- dxmt/types.py +51 -0
- dxmt_python_sdk-1.6.0.dist-info/METADATA +736 -0
- dxmt_python_sdk-1.6.0.dist-info/RECORD +23 -0
- dxmt_python_sdk-1.6.0.dist-info/WHEEL +5 -0
- dxmt_python_sdk-1.6.0.dist-info/licenses/LICENSE +201 -0
- dxmt_python_sdk-1.6.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,736 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dxmt-python-sdk
|
|
3
|
+
Version: 1.6.0
|
|
4
|
+
Summary: Python SDK for DXMT, the open-source memory database for personal agents
|
|
5
|
+
Author-email: DXMT Team <contact@dxmt.online>
|
|
6
|
+
License: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/dxmt/dxmt
|
|
8
|
+
Project-URL: Documentation, https://docs.dxmt.online
|
|
9
|
+
Project-URL: Repository, https://github.com/dxmt/dxmt
|
|
10
|
+
Project-URL: Issues, https://github.com/dxmt/dxmt/issues
|
|
11
|
+
Keywords: vector-database,vector-search,embeddings,similarity-search,dxmt,vectordb
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
21
|
+
Classifier: Topic :: Database
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: httpx>=0.24.0
|
|
27
|
+
Provides-Extra: fast
|
|
28
|
+
Requires-Dist: orjson>=3.9.0; extra == "fast"
|
|
29
|
+
Provides-Extra: chroma
|
|
30
|
+
Requires-Dist: chromadb>=0.5; extra == "chroma"
|
|
31
|
+
Provides-Extra: examples
|
|
32
|
+
Requires-Dist: numpy>=1.24; extra == "examples"
|
|
33
|
+
Requires-Dist: sentence-transformers>=2.2; extra == "examples"
|
|
34
|
+
Requires-Dist: openai>=1.0; extra == "examples"
|
|
35
|
+
Requires-Dist: langgraph>=0.2; extra == "examples"
|
|
36
|
+
Provides-Extra: dev
|
|
37
|
+
Requires-Dist: pytest>=7.4.0; extra == "dev"
|
|
38
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
39
|
+
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
|
|
40
|
+
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
|
|
41
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
42
|
+
Requires-Dist: mypy>=1.5.0; extra == "dev"
|
|
43
|
+
Dynamic: license-file
|
|
44
|
+
|
|
45
|
+
# DXMT Python SDK
|
|
46
|
+
|
|
47
|
+
[](https://badge.fury.io/py/dxmt-python-sdk)
|
|
48
|
+
[](https://pypi.org/project/dxmt-python-sdk/)
|
|
49
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
50
|
+
|
|
51
|
+
Official Python SDK for DXMT VectorDB - a lightweight single-node vector database written in Rust.
|
|
52
|
+
|
|
53
|
+
## Features
|
|
54
|
+
|
|
55
|
+
- 🚀 **Simple API** - Clean, intuitive Python interface
|
|
56
|
+
- ⚡ **Async Support** - Full async/await support for high performance
|
|
57
|
+
- 🔍 **Vector Search** - Multiple distance metrics (Cosine, Euclidean, Manhattan, Dot Product)
|
|
58
|
+
- 📊 **Multiple Index Types** - HNSW, IVF, IVF-PQ, LSH, Brute Force
|
|
59
|
+
- 📝 **Full-Text Search** - BM25 with Tantivy integration
|
|
60
|
+
- 🔀 **Hybrid Search** - Combine vector similarity + full-text search
|
|
61
|
+
- 🇨🇳 **Chinese Support** - Jieba tokenizer for Chinese text
|
|
62
|
+
- 🎯 **Type Safe** - Full type hints with mypy support
|
|
63
|
+
- 📦 **Zero Dependencies** - Only requires httpx
|
|
64
|
+
|
|
65
|
+
> **⚠️ Important Note (Updated 2026-01-22):**
|
|
66
|
+
> When using full-text search or hybrid search, **you must use the `content` field** in your payload for main text content.
|
|
67
|
+
> Using other field names like `"text"` will cause full-text search to return 0 results.
|
|
68
|
+
> See [Field Naming Conventions](#field-naming-conventions) for details.
|
|
69
|
+
|
|
70
|
+
## Installation
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
pip install dxmt-python-sdk
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The package is not on PyPI yet. Until the packages are published, install from source:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pip install "git+https://github.com/dxmt/dxmt#subdirectory=vectordb/clients/dxmt-python-sdk"
|
|
80
|
+
# or, from a checkout of the repository:
|
|
81
|
+
pip install ./vectordb/clients/dxmt-python-sdk
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Quick Start
|
|
85
|
+
|
|
86
|
+
### Basic Usage
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
from dxmt import Client
|
|
90
|
+
|
|
91
|
+
# Connect to DXMT server
|
|
92
|
+
client = Client(host="localhost", port=9999)
|
|
93
|
+
|
|
94
|
+
# Create a table
|
|
95
|
+
client.create_table(
|
|
96
|
+
name="documents",
|
|
97
|
+
dimension=1536,
|
|
98
|
+
distance_metric="cosine",
|
|
99
|
+
index_type="hnsw"
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
# Insert vectors
|
|
103
|
+
client.insert_records(
|
|
104
|
+
table_name="documents",
|
|
105
|
+
records=[
|
|
106
|
+
{
|
|
107
|
+
"id": "doc1",
|
|
108
|
+
"vector": [0.1, 0.2, 0.3, ...], # 1536-dim vector
|
|
109
|
+
"payload": {
|
|
110
|
+
"title": "Document 1",
|
|
111
|
+
"content": "This is document 1",
|
|
112
|
+
"source": "file.txt"
|
|
113
|
+
}
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"id": "doc2",
|
|
117
|
+
"vector": [0.4, 0.5, 0.6, ...],
|
|
118
|
+
"payload": {
|
|
119
|
+
"title": "Document 2",
|
|
120
|
+
"content": "This is document 2",
|
|
121
|
+
"source": "file.txt"
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
]
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
# Search for similar vectors
|
|
128
|
+
results = client.search(
|
|
129
|
+
table_name="documents",
|
|
130
|
+
vector=[0.1, 0.2, 0.3, ...], # query vector
|
|
131
|
+
limit=10
|
|
132
|
+
)
|
|
133
|
+
|
|
134
|
+
for result in results:
|
|
135
|
+
print(f"ID: {result['id']}, Score: {result['score']}")
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Authentication
|
|
139
|
+
|
|
140
|
+
A server started with `DXMT_API_KEY` answers 401 to everything but its health probes until the key is sent. It goes out as the `api-key` header; send it over TLS, or it is readable at every hop.
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
client = Client(host="db.example.com", ssl=True, api_key="your-key")
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
The client reads no environment variable itself — pass `api_key=os.environ["DXMT_API_KEY"]` if that
|
|
147
|
+
is where you keep it. Over plain HTTP to anything but localhost it warns.
|
|
148
|
+
|
|
149
|
+
### Loading and Exporting a Table
|
|
150
|
+
|
|
151
|
+
`upload` inserts any iterable of records — a generator included, drawn a batch at a time — in
|
|
152
|
+
batches, in parallel if asked, retrying what a retry can fix (a dropped connection, a timeout,
|
|
153
|
+
429, a 5xx) and reporting what could not go in rather than raising halfway:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
result = client.upload("docs", records, batch_size=256, parallel=4)
|
|
157
|
+
if not result.ok:
|
|
158
|
+
for failure in result.failed:
|
|
159
|
+
print(failure.status, failure.error, failure.ids)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`scroll` reads every record back, newest first, a page at a time. It pages by cursor, so every
|
|
163
|
+
record present for the whole scroll comes back exactly once even while the table is written to —
|
|
164
|
+
where `list_records` with an offset shifts under inserts and repeats or skips records:
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
for record in client.scroll("docs", batch_size=500, filter={"must": [...]}):
|
|
168
|
+
...
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Async Usage
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
import asyncio
|
|
175
|
+
from dxmt import Client
|
|
176
|
+
|
|
177
|
+
async def main():
|
|
178
|
+
client = Client(host="localhost", port=9999)
|
|
179
|
+
|
|
180
|
+
# Create table
|
|
181
|
+
await client.acreate_table(
|
|
182
|
+
name="documents",
|
|
183
|
+
dimension=1536,
|
|
184
|
+
distance_metric="cosine"
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
# Insert records
|
|
188
|
+
await client.ainsert_records(
|
|
189
|
+
table_name="documents",
|
|
190
|
+
records=[...]
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
# Search
|
|
194
|
+
results = await client.asearch(
|
|
195
|
+
table_name="documents",
|
|
196
|
+
vector=[0.1, 0.2, ...],
|
|
197
|
+
limit=10
|
|
198
|
+
)
|
|
199
|
+
|
|
200
|
+
await client.aclose()
|
|
201
|
+
|
|
202
|
+
asyncio.run(main())
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Context Manager
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
from dxmt import Client
|
|
209
|
+
|
|
210
|
+
# Automatic cleanup
|
|
211
|
+
with Client(host="localhost", port=9999) as client:
|
|
212
|
+
client.create_table(name="test", dimension=128)
|
|
213
|
+
# ... do work ...
|
|
214
|
+
|
|
215
|
+
# Async context manager
|
|
216
|
+
async with Client(host="localhost", port=9999) as client:
|
|
217
|
+
await client.acreate_table(name="test", dimension=128)
|
|
218
|
+
# ... do work ...
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Hybrid Search (Vector + Text)
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
from dxmt import Client
|
|
225
|
+
|
|
226
|
+
client = Client(host="localhost", port=9999)
|
|
227
|
+
|
|
228
|
+
# Create table with full-text search enabled
|
|
229
|
+
client.create_table(
|
|
230
|
+
name="documents",
|
|
231
|
+
dimension=1536,
|
|
232
|
+
distance_metric="cosine",
|
|
233
|
+
enable_full_text_search=True # Enable text search
|
|
234
|
+
)
|
|
235
|
+
|
|
236
|
+
# Insert documents with "content" field for text search
|
|
237
|
+
client.insert_records(
|
|
238
|
+
table_name="documents",
|
|
239
|
+
records=[
|
|
240
|
+
{
|
|
241
|
+
"id": "doc1",
|
|
242
|
+
"vector": embedding1,
|
|
243
|
+
"payload": {
|
|
244
|
+
"title": "Machine Learning Guide",
|
|
245
|
+
"content": "Machine learning is...", # Required for text search
|
|
246
|
+
"category": "AI"
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
]
|
|
250
|
+
)
|
|
251
|
+
|
|
252
|
+
# Hybrid search: combine vector similarity + text matching
|
|
253
|
+
results = client.hybrid_search(
|
|
254
|
+
table_name="documents",
|
|
255
|
+
vector=[0.1, 0.2, ...], # Vector query
|
|
256
|
+
text_query="machine learning", # Text query
|
|
257
|
+
vector_weight=0.5, # 0=text only, 1=vector only; omit to let the server fuse with dbsf
|
|
258
|
+
limit=10
|
|
259
|
+
)
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### Table Management
|
|
263
|
+
|
|
264
|
+
```python
|
|
265
|
+
from dxmt import Client
|
|
266
|
+
|
|
267
|
+
client = Client()
|
|
268
|
+
|
|
269
|
+
# List all tables
|
|
270
|
+
tables = client.list_tables()
|
|
271
|
+
print(f"Tables: {tables}")
|
|
272
|
+
|
|
273
|
+
# Get table info
|
|
274
|
+
info = client.get_table("documents")
|
|
275
|
+
print(f"Dimension: {info['dimension']}")
|
|
276
|
+
print(f"Distance: {info['distance_metric']}")
|
|
277
|
+
|
|
278
|
+
# Delete table
|
|
279
|
+
client.delete_table("documents")
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Record Operations
|
|
283
|
+
|
|
284
|
+
```python
|
|
285
|
+
# Get records by IDs
|
|
286
|
+
records = client.get_records(
|
|
287
|
+
table_name="documents",
|
|
288
|
+
ids=["doc1", "doc2"]
|
|
289
|
+
)
|
|
290
|
+
|
|
291
|
+
# Delete records
|
|
292
|
+
client.delete_records(
|
|
293
|
+
table_name="documents",
|
|
294
|
+
ids=["doc1", "doc2"]
|
|
295
|
+
)
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Field Naming Conventions
|
|
299
|
+
|
|
300
|
+
### Standard Payload Fields
|
|
301
|
+
|
|
302
|
+
DXMT uses specific field names for optimal functionality, especially when using **full-text search** and **hybrid search**:
|
|
303
|
+
|
|
304
|
+
| Field Name | Purpose | Required | Example |
|
|
305
|
+
|-----------|---------|----------|---------|
|
|
306
|
+
| `content` | Main searchable text content | **Yes** for text search | Article body, document content |
|
|
307
|
+
| `title` | Document title (higher search boost) | No | "Introduction to AI" |
|
|
308
|
+
| `description` | Brief description/summary | No | "An overview of..." |
|
|
309
|
+
| `tags` | Categorization tags | No | ["AI", "ML"] |
|
|
310
|
+
|
|
311
|
+
### ⚠️ Important: Use `content` for Text Search
|
|
312
|
+
|
|
313
|
+
When using full-text search or hybrid search, **you must use the `content` field** for your main text:
|
|
314
|
+
|
|
315
|
+
```python
|
|
316
|
+
# ✅ CORRECT - Use "content"
|
|
317
|
+
records = [{
|
|
318
|
+
"id": "doc1",
|
|
319
|
+
"vector": [0.1, 0.2, ...],
|
|
320
|
+
"payload": {
|
|
321
|
+
"title": "Introduction to Machine Learning",
|
|
322
|
+
"content": "Machine learning is a subset of AI...", # ✅
|
|
323
|
+
"category": "AI"
|
|
324
|
+
}
|
|
325
|
+
}]
|
|
326
|
+
|
|
327
|
+
# ❌ WRONG - Don't use "text" or other field names
|
|
328
|
+
records = [{
|
|
329
|
+
"id": "doc1",
|
|
330
|
+
"vector": [0.1, 0.2, ...],
|
|
331
|
+
"payload": {
|
|
332
|
+
"title": "Introduction to Machine Learning",
|
|
333
|
+
"text": "Machine learning is...", # ❌ Won't work!
|
|
334
|
+
"category": "AI"
|
|
335
|
+
}
|
|
336
|
+
}]
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### Why Field Names Matter
|
|
340
|
+
|
|
341
|
+
The full-text search engine (Tantivy) maps payload fields to its internal schema:
|
|
342
|
+
|
|
343
|
+
- `content` → Main searchable field (BM25 ranking)
|
|
344
|
+
- `title` → Title field (2x boost in search)
|
|
345
|
+
- `description` → Description field (0.8x boost)
|
|
346
|
+
- `tags` → Tags field (1.5x boost, supports filtering)
|
|
347
|
+
|
|
348
|
+
**If you use incorrect field names:**
|
|
349
|
+
- Full-text search will return 0 results
|
|
350
|
+
- Hybrid search text component will not work
|
|
351
|
+
- No error is thrown (silent failure)
|
|
352
|
+
|
|
353
|
+
### Full-Text Search Example
|
|
354
|
+
|
|
355
|
+
```python
|
|
356
|
+
# Create table with full-text search
|
|
357
|
+
client.create_table(
|
|
358
|
+
name="articles",
|
|
359
|
+
dimension=128,
|
|
360
|
+
distance_metric="cosine",
|
|
361
|
+
enable_full_text_search=True # Enable text search
|
|
362
|
+
)
|
|
363
|
+
|
|
364
|
+
# Insert with correct field names
|
|
365
|
+
client.insert_records(
|
|
366
|
+
table_name="articles",
|
|
367
|
+
records=[
|
|
368
|
+
{
|
|
369
|
+
"id": "art1",
|
|
370
|
+
"vector": embedding1,
|
|
371
|
+
"payload": {
|
|
372
|
+
"title": "Deep Learning Fundamentals",
|
|
373
|
+
"content": "Deep learning uses neural networks...", # ✅ Required
|
|
374
|
+
"category": "AI",
|
|
375
|
+
"tags": ["deep-learning", "neural-networks"]
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
]
|
|
379
|
+
)
|
|
380
|
+
|
|
381
|
+
# Full-text search
|
|
382
|
+
results = client.full_text_search(
|
|
383
|
+
table_name="articles",
|
|
384
|
+
text_query="neural networks",
|
|
385
|
+
limit=10
|
|
386
|
+
)
|
|
387
|
+
|
|
388
|
+
# Hybrid search (vector + text)
|
|
389
|
+
results = client.hybrid_search(
|
|
390
|
+
table_name="articles",
|
|
391
|
+
vector=query_embedding,
|
|
392
|
+
text_query="deep learning",
|
|
393
|
+
vector_weight=0.5, # 0.0 = text only, 1.0 = vector only; omit for the server's dbsf
|
|
394
|
+
limit=10
|
|
395
|
+
)
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
### Custom Metadata Fields
|
|
399
|
+
|
|
400
|
+
You can add any custom fields alongside the standard fields:
|
|
401
|
+
|
|
402
|
+
```python
|
|
403
|
+
"payload": {
|
|
404
|
+
"content": "Main text here...", # ✅ Required for text search
|
|
405
|
+
"title": "Document Title", # Standard field
|
|
406
|
+
"author": "John Doe", # ✅ Custom field
|
|
407
|
+
"publish_date": "2024-01-15", # ✅ Custom field
|
|
408
|
+
"rating": 4.5, # ✅ Custom field
|
|
409
|
+
"custom_metadata": {...} # ✅ Any structure
|
|
410
|
+
}
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### Migration from Old Code
|
|
414
|
+
|
|
415
|
+
If your code uses `"text"` field, update it to `"content"`:
|
|
416
|
+
|
|
417
|
+
```python
|
|
418
|
+
# Old code (before 2026-01-22)
|
|
419
|
+
"payload": {"text": "..."}
|
|
420
|
+
|
|
421
|
+
# New code (after 2026-01-22)
|
|
422
|
+
"payload": {"content": "..."} # ✅ Required change
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
After updating field names, you need to:
|
|
426
|
+
1. Re-create tables with full-text search
|
|
427
|
+
2. Re-insert all records with corrected field names
|
|
428
|
+
|
|
429
|
+
## Advanced Features
|
|
430
|
+
|
|
431
|
+
### Distance Metrics
|
|
432
|
+
|
|
433
|
+
```python
|
|
434
|
+
# Choose your distance metric
|
|
435
|
+
client.create_table(
|
|
436
|
+
name="table",
|
|
437
|
+
dimension=128,
|
|
438
|
+
distance_metric="cosine" # or "euclidean", "manhattan", "dot"
|
|
439
|
+
)
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
### Index Types
|
|
443
|
+
|
|
444
|
+
```python
|
|
445
|
+
# Choose optimal index for your use case
|
|
446
|
+
client.create_table(
|
|
447
|
+
name="table",
|
|
448
|
+
dimension=128,
|
|
449
|
+
index_type="hnsw" # Fast, high recall
|
|
450
|
+
# or: "ivf", "ivf_pq" (memory efficient), "lsh", "brute_force"
|
|
451
|
+
)
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
### Insert Modes
|
|
455
|
+
|
|
456
|
+
```python
|
|
457
|
+
# One call is one request, so bigger batches amortise the round trip
|
|
458
|
+
client.insert_records(table_name="documents", records=[...])
|
|
459
|
+
|
|
460
|
+
# Or let upload() batch, parallelise and retry for you
|
|
461
|
+
client.upload("documents", records, batch_size=256, parallel=4)
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
### Filtering
|
|
465
|
+
|
|
466
|
+
```python
|
|
467
|
+
# Filter search results by metadata
|
|
468
|
+
results = client.search(
|
|
469
|
+
table_name="documents",
|
|
470
|
+
vector=[0.1, 0.2, ...],
|
|
471
|
+
limit=10,
|
|
472
|
+
filter={
|
|
473
|
+
"source": {"$eq": "file.txt"},
|
|
474
|
+
"date_ts": {"$gte": 1704067200} # ranges compare numbers: 2024-01-01 as a timestamp
|
|
475
|
+
}
|
|
476
|
+
)
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
## Integrations
|
|
480
|
+
|
|
481
|
+
### Coming from Chroma
|
|
482
|
+
|
|
483
|
+
`python -m dxmt.migrate.chroma` copies Chroma collections into DXMT tables with their stored
|
|
484
|
+
vectors, so nothing is re-embedded: the same ids, the collection's distance (`l2` becomes
|
|
485
|
+
`euclidean`, `ip` becomes `dot`), each metadata dict as the payload, and the document under
|
|
486
|
+
`text` with a full-text index on it. Records are written by id, so a second run over the same
|
|
487
|
+
table rewrites them rather than duplicating them, and an interrupted copy is finished by
|
|
488
|
+
running it again.
|
|
489
|
+
|
|
490
|
+
```bash
|
|
491
|
+
pip install 'dxmt-python-sdk[chroma]' # until published: pip install './vectordb/clients/dxmt-python-sdk[chroma]'
|
|
492
|
+
python -m dxmt.migrate.chroma --path ./chroma_db # every collection
|
|
493
|
+
python -m dxmt.migrate.chroma --path ./chroma_db --collection notes --table notes --analyzer chinese
|
|
494
|
+
python -m dxmt.migrate.chroma --chroma-host localhost:8000 --url http://localhost:9999
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### mem0 Integration
|
|
498
|
+
|
|
499
|
+
DXMT can be used as a vector storage backend for [mem0](https://mem0.ai), an intelligent memory layer for AI agents.
|
|
500
|
+
|
|
501
|
+
**Installation:**
|
|
502
|
+
```bash
|
|
503
|
+
pip install mem0ai dxmt-python-sdk # until published: pip install mem0ai ./vectordb/clients/dxmt-python-sdk
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
**Usage:**
|
|
507
|
+
```python
|
|
508
|
+
from mem0 import Memory
|
|
509
|
+
from dxmt import Client
|
|
510
|
+
from dxmt.mem0 import DXMTMemoryStore
|
|
511
|
+
|
|
512
|
+
# Initialize DXMT client
|
|
513
|
+
client = Client(host="localhost", port=9999)
|
|
514
|
+
|
|
515
|
+
# Create DXMT memory store
|
|
516
|
+
vector_store = DXMTMemoryStore(
|
|
517
|
+
collection_name="user_memories",
|
|
518
|
+
client=client,
|
|
519
|
+
embedding_model_dims=1536 # OpenAI text-embedding-ada-002
|
|
520
|
+
)
|
|
521
|
+
|
|
522
|
+
# Configure mem0
|
|
523
|
+
config = {
|
|
524
|
+
"vector_store": {
|
|
525
|
+
"provider": "custom",
|
|
526
|
+
"config": {"custom_vector_store": vector_store}
|
|
527
|
+
},
|
|
528
|
+
"embedder": {
|
|
529
|
+
"provider": "openai",
|
|
530
|
+
"config": {"model": "text-embedding-ada-002"}
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
m = Memory.from_config(config)
|
|
535
|
+
|
|
536
|
+
# Store memories
|
|
537
|
+
m.add("I love Python programming", user_id="user_123")
|
|
538
|
+
|
|
539
|
+
# Search memories
|
|
540
|
+
results = m.search("programming preferences", user_id="user_123")
|
|
541
|
+
for mem in results:
|
|
542
|
+
print(f"{mem['memory']} (score: {mem['score']:.3f})")
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
**Features:**
|
|
546
|
+
- Multi-scope memory (user_id, agent_id, run_id)
|
|
547
|
+
- Automatic deduplication via hash
|
|
548
|
+
- Efficient filtering and semantic search
|
|
549
|
+
- Timestamp tracking (created_at, updated_at)
|
|
550
|
+
|
|
551
|
+
|
|
552
|
+
## API Reference
|
|
553
|
+
|
|
554
|
+
### Client
|
|
555
|
+
|
|
556
|
+
#### `__init__(host="localhost", port=9999, ssl=False, timeout=30.0)`
|
|
557
|
+
|
|
558
|
+
Create a new DXMT client.
|
|
559
|
+
|
|
560
|
+
**Parameters:**
|
|
561
|
+
- `host` (str): Server hostname
|
|
562
|
+
- `port` (int): Server port
|
|
563
|
+
- `ssl` (bool): Use HTTPS
|
|
564
|
+
- `timeout` (float): Request timeout in seconds
|
|
565
|
+
|
|
566
|
+
#### `create_table(name, dimension, distance_metric="cosine", index_type="hnsw", **kwargs)`
|
|
567
|
+
|
|
568
|
+
Create a new table.
|
|
569
|
+
|
|
570
|
+
**Parameters:**
|
|
571
|
+
- `name` (str): Table name
|
|
572
|
+
- `dimension` (int): Vector dimension
|
|
573
|
+
- `distance_metric` (str): Distance metric ("cosine", "euclidean", "manhattan", "dot")
|
|
574
|
+
- `index_type` (str): Index type ("hnsw", "ivf", "ivf_pq", "lsh", "brute_force")
|
|
575
|
+
|
|
576
|
+
#### `insert_records(table_name, records)`
|
|
577
|
+
|
|
578
|
+
Insert records into a table.
|
|
579
|
+
|
|
580
|
+
**Parameters:**
|
|
581
|
+
- `table_name` (str): Table name
|
|
582
|
+
- `records` (list[dict]): Records to insert (each record must have `id`, `vector`, and `payload`)
|
|
583
|
+
|
|
584
|
+
**Record Structure:**
|
|
585
|
+
```python
|
|
586
|
+
{
|
|
587
|
+
"id": "unique_id", # Required: Record ID
|
|
588
|
+
"vector": [0.1, 0.2, ...], # Required: Embedding vector
|
|
589
|
+
"payload": { # Required: Metadata
|
|
590
|
+
"content": "...", # For full-text search
|
|
591
|
+
"title": "...", # Optional
|
|
592
|
+
# ... custom fields
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
#### `search(table_name, vector=None, text=None, k=10, filter=None, search_mode=None, offset=0, mmr=None, ...)`
|
|
598
|
+
|
|
599
|
+
Search for similar vectors. `limit` is accepted as an alias for `k`.
|
|
600
|
+
|
|
601
|
+
**Parameters:**
|
|
602
|
+
- `table_name` (str): Table name
|
|
603
|
+
- `vector` (list[float]): Query vector -- or `text` (str) on a table with a server-side embedding model
|
|
604
|
+
- `k` (int): Number of results (default 10)
|
|
605
|
+
- `filter` (dict): Metadata filter
|
|
606
|
+
- `search_mode` (str): `fast` / `normal` / `accurate` / `exact`; `exact` scores every row and is the ground truth the others approximate
|
|
607
|
+
- `mmr` (dict): `{"lambda_mult": 0.5, "fetch_k": 50}` re-ranks the candidates for diversity
|
|
608
|
+
|
|
609
|
+
#### `hybrid_search(table_name, vector=None, text=None, vector_weight=None, fusion_method=None, k=10, filter=None)`
|
|
610
|
+
|
|
611
|
+
Hybrid search combining vector + text. Needs a server built with `text-bm25`; a default build
|
|
612
|
+
refuses a request carrying `text` with `FEATURE_DISABLED` rather than answering from the vector alone.
|
|
613
|
+
`text_query`, `alpha` and `limit` are accepted as aliases for `text`, `vector_weight` and `k`.
|
|
614
|
+
|
|
615
|
+
**Parameters:**
|
|
616
|
+
- `table_name` (str): Table name
|
|
617
|
+
- `vector` (list[float]): Query vector
|
|
618
|
+
- `text` (str): Text query
|
|
619
|
+
- `vector_weight` (float): 0 = text only, 1 = vector only. **No default**: when omitted, nothing is sent and
|
|
620
|
+
the server fuses with `dbsf`, which normalises each side by its own score distribution and has no weight to
|
|
621
|
+
tune. Passing a weight selects `weighted_sum` unless `fusion_method` names another method
|
|
622
|
+
(`reciprocal_rank_fusion` also reads the weight).
|
|
623
|
+
- `k` (int): Number of results
|
|
624
|
+
|
|
625
|
+
### Async Methods
|
|
626
|
+
|
|
627
|
+
All methods have async equivalents with `a` prefix:
|
|
628
|
+
- `acreate_table()`, `ainsert_records()`, `asearch()`, etc.
|
|
629
|
+
|
|
630
|
+
### Metadata Filters
|
|
631
|
+
|
|
632
|
+
DXMT supports flexible metadata filtering with MongoDB-style operators. See **[FILTERS_GUIDE.md](FILTERS_GUIDE.md)** for comprehensive documentation.
|
|
633
|
+
|
|
634
|
+
Quick examples:
|
|
635
|
+
|
|
636
|
+
```python
|
|
637
|
+
# Simple equality
|
|
638
|
+
filter = {"category": "AI", "year": 2023}
|
|
639
|
+
|
|
640
|
+
# Comparison operators
|
|
641
|
+
filter = {"rating": {"$gte": 8.0}, "year": {"$lt": 2024}}
|
|
642
|
+
|
|
643
|
+
# Logical operators
|
|
644
|
+
filter = {
|
|
645
|
+
"$and": [
|
|
646
|
+
{"year": {"$gte": 2022}},
|
|
647
|
+
{"rating": {"$gte": 8.0}},
|
|
648
|
+
{"category": {"$in": ["AI", "ML", "DL"]}}
|
|
649
|
+
]
|
|
650
|
+
}
|
|
651
|
+
|
|
652
|
+
# Use in search
|
|
653
|
+
results = client.search(
|
|
654
|
+
table_name="documents",
|
|
655
|
+
vector=query_vector,
|
|
656
|
+
limit=10,
|
|
657
|
+
filter=filter
|
|
658
|
+
)
|
|
659
|
+
|
|
660
|
+
# Or build the same thing with Field
|
|
661
|
+
from dxmt import Field
|
|
662
|
+
|
|
663
|
+
filter = (Field("year") >= 2022) & (Field("rating") >= 8.0) & Field("category").is_in(["AI", "ML"])
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
A filter that has no exact translation -- `(a and b) or c`, two `$or` groups, a range with a
|
|
667
|
+
string bound -- raises `ValueError` rather than running as a different query.
|
|
668
|
+
|
|
669
|
+
**Supported operators:**
|
|
670
|
+
- Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
|
|
671
|
+
- Array: `$in`, `$nin`
|
|
672
|
+
- String: `$contains`, `$startswith`, `$endswith`
|
|
673
|
+
- Logical: `$and`, `$or`, `$nor` (`$not` with a list is the same)
|
|
674
|
+
|
|
675
|
+
## Development
|
|
676
|
+
|
|
677
|
+
### Setup
|
|
678
|
+
|
|
679
|
+
```bash
|
|
680
|
+
# Clone repository
|
|
681
|
+
git clone https://github.com/dxmt/dxmt.git
|
|
682
|
+
cd dxmt/vectordb/clients/dxmt-python-sdk
|
|
683
|
+
|
|
684
|
+
# Create virtual environment
|
|
685
|
+
python3 -m venv venv
|
|
686
|
+
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
687
|
+
|
|
688
|
+
# Install in development mode
|
|
689
|
+
pip install -e ".[dev]"
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
### Testing
|
|
693
|
+
|
|
694
|
+
```bash
|
|
695
|
+
# Run tests
|
|
696
|
+
pytest
|
|
697
|
+
|
|
698
|
+
# Run with coverage
|
|
699
|
+
pytest --cov=dxmt --cov-report=term-missing
|
|
700
|
+
|
|
701
|
+
# Run specific test file
|
|
702
|
+
pytest tests/test_client.py -v
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
### Code Quality
|
|
706
|
+
|
|
707
|
+
```bash
|
|
708
|
+
# Lint
|
|
709
|
+
ruff check dxmt
|
|
710
|
+
|
|
711
|
+
# Format
|
|
712
|
+
ruff format dxmt
|
|
713
|
+
|
|
714
|
+
# Type check
|
|
715
|
+
mypy dxmt
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
## Requirements
|
|
719
|
+
|
|
720
|
+
- Python 3.9+
|
|
721
|
+
- DXMT VectorDB server (running locally or remotely)
|
|
722
|
+
|
|
723
|
+
## License
|
|
724
|
+
|
|
725
|
+
Apache License 2.0 - see [LICENSE](LICENSE) file for details.
|
|
726
|
+
|
|
727
|
+
## Links
|
|
728
|
+
|
|
729
|
+
- **Homepage**: https://github.com/dxmt/dxmt
|
|
730
|
+
- **Documentation**: https://docs.dxmt.online
|
|
731
|
+
- **Issues**: https://github.com/dxmt/dxmt/issues
|
|
732
|
+
- **PyPI**: https://pypi.org/project/dxmt-python-sdk/
|
|
733
|
+
|
|
734
|
+
## Contributing
|
|
735
|
+
|
|
736
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|