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.
@@ -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
+ [![PyPI version](https://badge.fury.io/py/dxmt-python-sdk.svg)](https://badge.fury.io/py/dxmt-python-sdk)
48
+ [![Python Version](https://img.shields.io/pypi/pyversions/dxmt-python-sdk)](https://pypi.org/project/dxmt-python-sdk/)
49
+ [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](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.