pyvastbase 0.2.8__tar.gz → 0.2.9__tar.gz

{pyvastbase-0.2.8 → pyvastbase-0.2.9}/MANIFEST.in

@@ -18,5 +18,10 @@ prune .ruff_cache
 prune .coverage
 prune .claude
 prune .scratch
+# Internal dev-convention docs — not shipped in the published package
+exclude CLAUDE.md
+exclude CONTEXT.md
+prune docs/adr
+prune docs/agents
 global-exclude *.pyc
 global-exclude __pycache__

{pyvastbase-0.2.8 → pyvastbase-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyvastbase
-Version: 0.2.8
+Version: 0.2.9
 Summary: Python SDK for Vastbase V3 (PyMilvus-style API)
 Author-email: "zhangzhijie(字节)" <zhangzj@vastdata.com.cn>
 License-Expression: MIT
@@ -72,7 +72,10 @@ results = client.search("my_vectors", data=[0.15] * 128, limit=5)
 db_info = client.describe_database("vastbase")
 print(db_info)  # {'name': 'vastbase', 'table_count': 5, ...}
 
-results = client.hybrid_search("my_vectors", data=[0.15] * 128, filter="price < 1000", limit=20)
+# 多路向量召回 + 重排序（pymilvus 兼容）
+from pyvastbase import AnnSearchRequest, RRFRanker
+req = AnnSearchRequest(data=[0.15] * 128, anns_field="embedding", limit=20)
+results = client.hybrid_search("my_vectors", reqs=[req], ranker=RRFRanker(), limit=20)
 ```
 
 ### 方式二：传统 Collection 风格
@@ -238,12 +241,12 @@ results = bm25_search_highlight(
 # 返回: ['<b>向量</b>数据库是AI应用的核心', ...]
 ```
 
-## 混合搜索
+## 混合 ANN 搜索（hybrid_ann_search）
 
-将向量相似度与标量字段过滤结合，实现灵活的复合查询：
+Vastbase 原生单向量相似度 + 标量字段过滤（HybridANN 索引），实现灵活的复合查询：
 
 ```python
-results = col.hybrid_search(
+results = col.hybrid_ann_search(
     data=[0.1] * 128,
     filter={
         "$and": [
@@ -273,7 +276,7 @@ for buf in bulkbuffer_inspect():
 
 ## MutationResult
 
-所有变更操作返回 `MutationResultWrapper`，同时支持向后兼容的列表访问和完整的 `MutationResult` 接口：
+所有变更操作返回 `MutationResult`，支持列表访问和结构化字段（`MutationResultWrapper` 为废弃别名，访问会触发 `DeprecationWarning`，但仍可用）：
 
 ```python
 result = col.insert([{"id": 1, "embedding": [0.1] * 128, "text": "hello"}])
@@ -389,7 +392,7 @@ except ConnectionError:
 | [ORM](docs/api-reference_zh.md#orm) | Entity, Model, Field, VectorField |
 | [Exceptions](docs/api-reference_zh.md#exceptions) | VastbaseException 继承层次 |
 | [Async API](docs/api-reference_zh.md#async-api) | AsyncCollection, AsyncConnections |
-| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult, MutationResultWrapper |
+| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult（MutationResultWrapper 为废弃别名） |
 
 ## 快速 API 参考
 
@@ -443,12 +446,13 @@ col.create()
 col.drop()
 col.exists()
 col.truncate()
-col.insert(data, normalize_vectors=False)          # -> MutationResultWrapper
+col.insert(data, normalize_vectors=False)          # -> MutationResult
 col.batch_insert(data, batch_size=100)
 col.delete(expr="id > 10") | delete(pks=[1, 2, 3])
 col.upsert(data)
 col.search(data, anns_field, param, limit, expr, output_fields)
-col.hybrid_search(data, anns_field, param, limit, filter, output_fields)
+col.hybrid_search(reqs, rerank, limit, output_fields)
+col.hybrid_ann_search(data, anns_field, param, limit, filter, output_fields)
 col.query(expr="id < 100", limit=10, offset=0, batch_size=None)
 col.get(ids=[1, 2, 3])
 col.num_entities / col.is_empty
@@ -500,7 +504,7 @@ get_config()  # -> {"default_connection": "default", "timeout": 30.0, ...}
 以下功能已与 pymilvus API 对齐：
 
 - **DataType IntEnum** — 所有标量和向量类型使用 IntEnum，与 pymilvus 枚举值兼容
-- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResultWrapper`，同时支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）
+- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResult`，支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）；`MutationResultWrapper` 为废弃别名
 - **SearchResult** — 搜索结果结构与 pymilvus 一致，支持 `result.id`, `result.distance`, `result.data`
 - **connect(uri)** — 支持通过 URI 连接字符串连接（`postgresql://user:pass@host:port/db`）
 - **hybrid_search** — SDK 层多路向量召回 + RRF/WeightedRRF/WeightedRanker 重排序（pymilvus 兼容 API）
@@ -565,7 +569,7 @@ pyvastbase/
 │   ├── constants.py       # IndexType, DistanceType, 版本常量, 算子映射
 │   ├── connections.py     # ConnectionConfig, VastbaseConnection (含版本缓存)
 │   ├── exceptions.py      # 19 个异常类
-│   ├── mutation_result.py # MutationResult, MutationResultWrapper
+│   ├── mutation_result.py # MutationResult（含 MutationResultWrapper 废弃别名）
 │   └── schema.py          # FieldSchema, CollectionSchema, DataType
 ├── collection.py          # Collection 类，完整的 CRUD、搜索、索引操作
 ├── utility.py             # 50+ 工具函数：用户/数据库/权限, flush/compact, 3.0.9+特性
@@ -576,7 +580,7 @@ pyvastbase/
 ├── utils/                 # SQL 生成, 向量/距离/过滤/结果工具
 ├── orm/                   # Entity/Model ORM 层 (Django 风格装饰器)
 ├── async_impl/            # AsyncCollection 等异步对应实现
-├── tests/                 # 1100+ 测试覆盖所有模块
+├── tests/                 # 1700+ 测试覆盖所有模块
 └── docs/
     ├── api-reference.md   # 完整 API 参考（英文）
     └── api-reference_zh.md # 完整 API 参考（简体中文）

{pyvastbase-0.2.8 → pyvastbase-0.2.9}/README.md

@@ -34,7 +34,10 @@ results = client.search("my_vectors", data=[0.15] * 128, limit=5)
 db_info = client.describe_database("vastbase")
 print(db_info)  # {'name': 'vastbase', 'table_count': 5, ...}
 
-results = client.hybrid_search("my_vectors", data=[0.15] * 128, filter="price < 1000", limit=20)
+# 多路向量召回 + 重排序（pymilvus 兼容）
+from pyvastbase import AnnSearchRequest, RRFRanker
+req = AnnSearchRequest(data=[0.15] * 128, anns_field="embedding", limit=20)
+results = client.hybrid_search("my_vectors", reqs=[req], ranker=RRFRanker(), limit=20)
 ```
 
 ### 方式二：传统 Collection 风格
@@ -200,12 +203,12 @@ results = bm25_search_highlight(
 # 返回: ['<b>向量</b>数据库是AI应用的核心', ...]
 ```
 
-## 混合搜索
+## 混合 ANN 搜索（hybrid_ann_search）
 
-将向量相似度与标量字段过滤结合，实现灵活的复合查询：
+Vastbase 原生单向量相似度 + 标量字段过滤（HybridANN 索引），实现灵活的复合查询：
 
 ```python
-results = col.hybrid_search(
+results = col.hybrid_ann_search(
     data=[0.1] * 128,
     filter={
         "$and": [
@@ -235,7 +238,7 @@ for buf in bulkbuffer_inspect():
 
 ## MutationResult
 
-所有变更操作返回 `MutationResultWrapper`，同时支持向后兼容的列表访问和完整的 `MutationResult` 接口：
+所有变更操作返回 `MutationResult`，支持列表访问和结构化字段（`MutationResultWrapper` 为废弃别名，访问会触发 `DeprecationWarning`，但仍可用）：
 
 ```python
 result = col.insert([{"id": 1, "embedding": [0.1] * 128, "text": "hello"}])
@@ -351,7 +354,7 @@ except ConnectionError:
 | [ORM](docs/api-reference_zh.md#orm) | Entity, Model, Field, VectorField |
 | [Exceptions](docs/api-reference_zh.md#exceptions) | VastbaseException 继承层次 |
 | [Async API](docs/api-reference_zh.md#async-api) | AsyncCollection, AsyncConnections |
-| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult, MutationResultWrapper |
+| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult（MutationResultWrapper 为废弃别名） |
 
 ## 快速 API 参考
 
@@ -405,12 +408,13 @@ col.create()
 col.drop()
 col.exists()
 col.truncate()
-col.insert(data, normalize_vectors=False)          # -> MutationResultWrapper
+col.insert(data, normalize_vectors=False)          # -> MutationResult
 col.batch_insert(data, batch_size=100)
 col.delete(expr="id > 10") | delete(pks=[1, 2, 3])
 col.upsert(data)
 col.search(data, anns_field, param, limit, expr, output_fields)
-col.hybrid_search(data, anns_field, param, limit, filter, output_fields)
+col.hybrid_search(reqs, rerank, limit, output_fields)
+col.hybrid_ann_search(data, anns_field, param, limit, filter, output_fields)
 col.query(expr="id < 100", limit=10, offset=0, batch_size=None)
 col.get(ids=[1, 2, 3])
 col.num_entities / col.is_empty
@@ -462,7 +466,7 @@ get_config()  # -> {"default_connection": "default", "timeout": 30.0, ...}
 以下功能已与 pymilvus API 对齐：
 
 - **DataType IntEnum** — 所有标量和向量类型使用 IntEnum，与 pymilvus 枚举值兼容
-- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResultWrapper`，同时支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）
+- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResult`，支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）；`MutationResultWrapper` 为废弃别名
 - **SearchResult** — 搜索结果结构与 pymilvus 一致，支持 `result.id`, `result.distance`, `result.data`
 - **connect(uri)** — 支持通过 URI 连接字符串连接（`postgresql://user:pass@host:port/db`）
 - **hybrid_search** — SDK 层多路向量召回 + RRF/WeightedRRF/WeightedRanker 重排序（pymilvus 兼容 API）
@@ -527,7 +531,7 @@ pyvastbase/
 │   ├── constants.py       # IndexType, DistanceType, 版本常量, 算子映射
 │   ├── connections.py     # ConnectionConfig, VastbaseConnection (含版本缓存)
 │   ├── exceptions.py      # 19 个异常类
-│   ├── mutation_result.py # MutationResult, MutationResultWrapper
+│   ├── mutation_result.py # MutationResult（含 MutationResultWrapper 废弃别名）
 │   └── schema.py          # FieldSchema, CollectionSchema, DataType
 ├── collection.py          # Collection 类，完整的 CRUD、搜索、索引操作
 ├── utility.py             # 50+ 工具函数：用户/数据库/权限, flush/compact, 3.0.9+特性
@@ -538,7 +542,7 @@ pyvastbase/
 ├── utils/                 # SQL 生成, 向量/距离/过滤/结果工具
 ├── orm/                   # Entity/Model ORM 层 (Django 风格装饰器)
 ├── async_impl/            # AsyncCollection 等异步对应实现
-├── tests/                 # 1100+ 测试覆盖所有模块
+├── tests/                 # 1700+ 测试覆盖所有模块
 └── docs/
     ├── api-reference.md   # 完整 API 参考（英文）
     └── api-reference_zh.md # 完整 API 参考（简体中文）

{pyvastbase-0.2.8 → pyvastbase-0.2.9}/README_en.md

@@ -30,7 +30,10 @@ results = client.search("my_vectors", data=[0.15] * 128, limit=5)
 db_info = client.describe_database("vastbase")
 print(db_info)  # {'name': 'vastbase', 'table_count': 5, ...}
 
-results = client.hybrid_search("my_vectors", data=[0.15] * 128, filter="price < 1000", limit=20)
+# Multi-way vector recall + reranking (pymilvus-compatible)
+from pyvastbase import AnnSearchRequest, RRFRanker
+req = AnnSearchRequest(data=[0.15] * 128, anns_field="embedding", limit=20)
+results = client.hybrid_search("my_vectors", reqs=[req], ranker=RRFRanker(), limit=20)
 ```
 
 ### Traditional Collection-based
@@ -194,12 +197,12 @@ results = bm25_search_highlight(
 # Returns: ['<b>向量</b>数据库是AI应用的核心', ...]
 ```
 
-## Hybrid Search
+## Hybrid ANN Search (hybrid_ann_search)
 
-Combine vector similarity with scalar field filtering for flexible queries:
+Vastbase-native single-vector similarity + scalar field filtering (HybridANN index) for flexible queries:
 
 ```python
-results = col.hybrid_search(
+results = col.hybrid_ann_search(
     data=[0.1] * 128,
     filter={
         "$and": [
@@ -229,7 +232,7 @@ for buf in bulkbuffer_inspect():
 
 ## MutationResult
 
-All mutation operations return `MutationResultWrapper` which provides both backward-compatible list access and the full `MutationResult` interface:
+All mutation operations return a `MutationResult` providing both list access and structured fields (`MutationResultWrapper` is a deprecated alias that still works but emits a `DeprecationWarning`):
 
 ```python
 result = col.insert([{"id": 1, "embedding": [0.1] * 128, "text": "hello"}])
@@ -345,7 +348,7 @@ Full API reference: [docs/api-reference.md](docs/api-reference.md)
 | [ORM](docs/api-reference.md#orm) | Entity, Model, Field, VectorField |
 | [Exceptions](docs/api-reference.md#exceptions) | VastbaseException hierarchy |
 | [Async API](docs/api-reference.md#async-api) | AsyncCollection, AsyncConnections |
-| [MutationResult](docs/api-reference.md#mutationresult) | MutationResult, MutationResultWrapper |
+| [MutationResult](docs/api-reference.md#mutationresult) | MutationResult (MutationResultWrapper is a deprecated alias) |
 
 ## Quick API Reference
 
@@ -399,12 +402,13 @@ col.create()
 col.drop()
 col.exists()
 col.truncate()
-col.insert(data, normalize_vectors=False)          # -> MutationResultWrapper
+col.insert(data, normalize_vectors=False)          # -> MutationResult
 col.batch_insert(data, batch_size=100)
 col.delete(expr="id > 10") | delete(pks=[1, 2, 3])
 col.upsert(data)
 col.search(data, anns_field, param, limit, expr, output_fields)
-col.hybrid_search(data, anns_field, param, limit, filter, output_fields)
+col.hybrid_search(reqs, rerank, limit, output_fields)
+col.hybrid_ann_search(data, anns_field, param, limit, filter, output_fields)
 col.query(expr="id < 100", limit=10, offset=0, batch_size=None)
 col.get(ids=[1, 2, 3])
 col.num_entities / col.is_empty
@@ -454,7 +458,7 @@ get_config()  # -> {"default_connection": "default", "timeout": 30.0, ...}
 ### Aligned (matches pymilvus API)
 
 - **DataType IntEnum** -- Numeric values match pymilvus (e.g. `FLOAT_VECTOR=16`, `INT64=6`); PG-only types use values >= 100
-- **MutationResult** -- Same `.insert_count`, `.delete_count`, `.upsert_count`, `.primary_keys` fields; `MutationResultWrapper` adds backward-compatible list access
+- **MutationResult** -- Same `.insert_count`, `.delete_count`, `.upsert_count`, `.primary_keys` fields with backward-compatible list access (`MutationResultWrapper` is a deprecated alias)
 - **SearchResult** -- Same `.id`, `.distance`, `.entity` attribute pattern on result hits
 - **connect(uri)** -- Accepts PostgreSQL connection URI strings, same parameter pattern as pymilvus `connect()`
 - **hybrid_search** -- SDK-layer multi-way vector recall with RRF/WeightedRRF/WeightedRanker reranking (pymilvus-compatible API; N SQL round trips vs Milvus single gRPC call)
@@ -523,7 +527,7 @@ pyvastbase/
 │   ├── constants.py       # IndexType, DistanceType, version constants, operator mapping
 │   ├── connections.py     # ConnectionConfig, VastbaseConnection (with version cache)
 │   ├── exceptions.py      # 19 exception classes
-│   ├── mutation_result.py # MutationResult, MutationResultWrapper
+│   ├── mutation_result.py # MutationResult (incl. MutationResultWrapper deprecated alias)
 │   └── schema.py          # FieldSchema, CollectionSchema, DataType
 ├── collection.py          # Collection class with full CRUD, search, index ops
 ├── utility.py             # 50+ utility functions: user/DB/privilege, flush/compact, 3.0.9+
@@ -534,7 +538,7 @@ pyvastbase/
 ├── utils/                 # SQL generation, vector/distance/filter/result utilities
 ├── orm/                   # Entity/Model ORM layer (Django-style decorators)
 ├── async_impl/            # AsyncCollection, async counterparts
-├── tests/                 # 1100+ tests (unit + integration)
+├── tests/                 # 1700+ tests (unit + integration)
 └── docs/
     └── api-reference.md   # Full API reference in PyMilvus format
 ```
@@ -542,7 +546,7 @@ pyvastbase/
 ## Requirements
 
 - Python >= 3.9
-- psycopg[binary] >= 3.1
+- psycopg[binary] >= 3.2
 - Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2 (3.0.9+ for new vector types and features)
 
 ## License