Metadata-Version: 2.4
Name: pyxvector
Version: 1.0.0
Summary: Thin Python HTTP client for Xvector (Milvus REST v2 style)
Author-email: "Li Xiaolong (Timilong)" <timilong928@gmail.com>
Maintainer-email: "Li Xiaolong (Timilong)" <timilong928@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lxl0928/Xvector
Project-URL: Documentation, https://github.com/lxl0928/pyxvector/blob/main/README.md
Project-URL: Repository, https://github.com/lxl0928/Xvector
Project-URL: Source, https://github.com/lxl0928/pyxvector
Project-URL: Bug Tracker, https://github.com/lxl0928/Xvector/issues
Keywords: xvector,vector database,vector search,milvus,rest,http client,embedding,similarity search
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Dynamic: license-file

# pyxvector

**pyxvector** is a thin, dependency-light Python HTTP client for [Xvector](https://github.com/lxl0928/Xvector) — a vector database service that speaks Milvus REST v2 style APIs. It covers collections, partitions, indexes, aliases, entities (insert / upsert / delete / get / query), vector search, hybrid search, RBAC (users / roles / privileges) and bulk-import jobs.

<p align="center">
  <a href="https://pypi.org/project/pyxvector/"><img src="https://img.shields.io/pypi/v/pyxvector.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/pyxvector/"><img src="https://img.shields.io/pypi/pyversions/pyxvector.svg" alt="Python versions"></a>
  <a href="https://github.com/lxl0928/Xvector/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lxl0928/Xvector.svg" alt="License"></a>
</p>

---

## Supported Python versions

pyxvector supports **Python 3.9 – 3.13** (any Python `>= 3.9`):

| Python version | Supported |
| -------------- | --------- |
| 3.9            | ✅        |
| 3.10           | ✅        |
| 3.11           | ✅        |
| 3.12           | ✅        |
| 3.13           | ✅        |

## Dependencies

pyxvector only requires one runtime dependency:

| Package | Version constraint |
| ------- | ------------------ |
| [httpx](https://pypi.org/project/httpx/) | `>=0.27,<1` |

Install from PyPI:

```bash
pip install pyxvector
```

## Quick start

```python
from pyxvector import XvectorClient

client = XvectorClient(uri="http://127.0.0.1:19530", token="root:Xvector")

# 1. Create a collection with an Int64 primary key and a 4-dim float vector field
client.create_collection(
    "demo",
    schema={
        "fields": [
            {"name": "id", "dataType": "Int64", "isPrimaryKey": True},
            {"name": "vector", "dataType": "FloatVector", "dim": 4},
        ]
    },
)

# 2. Create an index and load the collection into memory
client.create_index("demo", "vector", index_type="FLAT", metric_type="L2")
client.load_collection("demo")

# 3. Insert rows
client.insert("demo", [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4]}])

# 4. Search immediately after write (refresh=True forces read-after-write consistency;
#    otherwise writes become visible within ~10s)
hits = client.search(
    "demo",
    [[0.1, 0.2, 0.3, 0.4]],
    anns_field="vector",
    limit=3,
    refresh=True,
)
print(hits)

# 5. Clean up
client.drop_collection("demo")
client.close()
```

`XvectorClient` is also a context manager:

```python
from pyxvector import XvectorClient

with XvectorClient(uri="http://127.0.0.1:19530", token="root:Xvector") as client:
    print(client.list_collections())
```

### Multi-database

```python
client.using_database("my_db")   # subsequent calls target the "my_db" database
```

## Error handling

All server-side errors are raised as `XvectorApiError` (a subclass of `XvectorError`), carrying the numeric `code` and `message` returned by the server:

```python
from pyxvector import XvectorClient, XvectorApiError

client = XvectorClient(uri="http://127.0.0.1:19530", token="root:Xvector")
try:
    client.describe_collection("not_exist")
except XvectorApiError as e:
    print(e.code, e.message)
```

## API overview

All methods map 1:1 to the Milvus REST v2 style endpoints (`/v2/vectordb/...`) exposed by Xvector.

| Area | Methods |
| ---- | ------- |
| Collection | `create_collection`, `drop_collection`, `describe_collection`, `has_collection`, `list_collections`, `rename_collection`, `load_collection`, `release_collection`, `get_load_state`, `get_collection_stats` |
| Partition | `create_partition`, `drop_partition`, `has_partition`, `list_partitions`, `load_partitions`, `release_partitions`, `get_partition_stats` |
| Index | `create_index`, `describe_index`, `drop_index`, `list_indexes` |
| Alias | `create_alias`, `drop_alias`, `alter_alias`, `describe_alias`, `list_aliases` |
| Entities | `insert`, `upsert`, `delete`, `get`, `query` |
| Search | `search`, `hybrid_search`, `search_after_write` |
| Database | `create_database`, `drop_database`, `list_databases`, `describe_database` |
| User | `create_user`, `drop_user`, `list_users`, `describe_user`, `update_password`, `grant_role`, `revoke_role` |
| Role | `create_role`, `drop_role`, `list_roles`, `describe_role`, `grant_privilege`, `revoke_privilege` |
| Import | `create_import_job`, `get_import_progress`, `list_import_jobs` |
| Helpers | `wait_loaded`, `wait_import_complete`, `close` |

### More examples

**Hybrid search with RRF rerank**

```python
client.hybrid_search(
    "demo",
    search=[
        {"data": [[0.1, 0.2, 0.3, 0.4]], "annsField": "vector", "limit": 10},
    ],
    rerank={"strategy": "rrf", "params": {"k": 60}},
    limit=5,
)
```

**Filtered query**

```python
rows = client.query("demo", filter="id >= 1", output_fields=["id"], limit=100, refresh=True)
```

**Bulk import from files**

```python
job = client.create_import_job("demo", files=["/data/batch1.json"], format="json")
client.wait_import_complete(job["jobId"])
```

**Wait until a collection is loaded**

```python
client.load_collection("demo")
client.wait_loaded("demo", timeout=30)
```

## Project links

- Project home / Xvector server: <https://github.com/lxl0928/Xvector>
- pyxvector source: <https://github.com/lxl0928/pyxvector>
- Issue tracker: <https://github.com/lxl0928/Xvector/issues>
- PyPI: <https://pypi.org/project/pyxvector/>

## GitHub statistics

Live stats for the Xvector repository:

<p>
  <a href="https://github.com/lxl0928/Xvector"><img src="https://img.shields.io/github/stars/lxl0928/Xvector?style=social" alt="GitHub stars"></a>
  <a href="https://github.com/lxl0928/Xvector"><img src="https://img.shields.io/github/forks/lxl0928/Xvector?style=social" alt="GitHub forks"></a>
  <a href="https://github.com/lxl0928/Xvector"><img src="https://img.shields.io/github/issues/lxl0928/Xvector" alt="GitHub issues"></a>
  <a href="https://github.com/lxl0928/Xvector"><img src="https://img.shields.io/github/last-commit/lxl0928/Xvector" alt="Last commit"></a>
</p>

## Maintainers

- **Li Xiaolong (Timilong)** — <timilong928@gmail.com> — [github.com/lxl0928](https://github.com/lxl0928)

## License

[MIT](https://github.com/lxl0928/Xvector/blob/main/LICENSE)
