@h-ai/vecdb 0.1.0-alpha.56 → 0.1.0-alpha.57

package/README.en.md

@@ -0,0 +1,145 @@
+# @h-ai/vecdb
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+
+A vector database module with a unified `vecdb` object for LanceDB, pgvector, Qdrant, and Chroma.
+
+## Supported vector databases
+
+- LanceDB (embedded, local file storage, zero configuration)
+- pgvector (PostgreSQL + pgvector extension)
+- Qdrant (high-performance vector search engine)
+- Chroma (automatically start a local service in embedded mode, or connect to an existing service)
+
+## Quick start
+
+```ts
+import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
+
+// 初始化（LanceDB）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// 创建集合
+await vecdb.collection.create('docs', { dimension: 1536 })
+
+// 插入向量
+await vecdb.vector.insert('docs', [
+  { id: 'doc-1', vector: Array.from({ length: 1536 }).fill(0.1), content: '文档内容', metadata: { source: 'wiki' } },
+])
+
+// 搜索
+const searchResult = await vecdb.vector.search('docs', Array.from({ length: 1536 }).fill(0.2), { topK: 5, minScore: 0.7 })
+if (searchResult.success) {
+  for (const item of searchResult.data) {
+    // item.id, item.score, item.content
+  }
+}
+
+// 关闭
+const closeResult = await vecdb.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
+```
+
+## Configuration
+
+```ts
+// LanceDB（默认，嵌入式本地存储）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// pgvector（连接字符串）
+await vecdb.init({ type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' })
+
+// pgvector（分字段）
+await vecdb.init({
+  type: 'pgvector',
+  host: 'localhost',
+  port: 5432,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  indexType: 'hnsw',
+  tablePrefix: 'vec_',
+})
+
+// Qdrant
+await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333', apiKey: 'optional-key' })
+
+// Chroma（嵌入式：自动拉起本地 `chroma run` 服务并持久化到 path）
+await vecdb.init({ type: 'chroma', path: './data/chroma' })
+
+// Chroma（直连已有服务，不拉起进程）
+await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
+```
+
+> On Node, Chroma provides only an HTTP client, with no in-process embedded database. In embedded mode, `vecdb.init`
+> starts a local service with `serverCommand` (default: `chroma`, from the `chromadb` package), and `vecdb.close`
+> stops the process. Install the optional `chromadb` dependency; if the command is unavailable, `init` returns `CONNECTION_FAILED`.
+
+### Operation logging
+
+Enable operation logging with `operationLog` in the vector database configuration. Logs are emitted before collection/vector operations reach the real provider, without a shared wrapper in `vecdb-main.ts`.
+
+```yaml
+# config/_vecdb.yml
+type: lancedb
+path: ./data/vecdb
+operationLog:
+  read: false # collection.exists/info/list, vector.search/count
+  write: false # collection.create/drop, vector.insert/upsert/delete
+  maxLength: 1000 # 参数序列化后的最大输出长度，超出会截断
+  level: debug # info | debug | trace，默认 debug
+```
+
+```ts
+await vecdb.init({
+  type: 'lancedb',
+  path: './data/vecdb',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+> Note: `vecdb.config` returns a **redacted configuration snapshot**. Connection-string usernames/passwords, standalone `password`, and `apiKey` are replaced with `[REDACTED]`.
+
+> Behavior: empty batch `insert/upsert/delete` calls are no-ops. Writes and searches validate vector dimensions, returning `HaiVecdbError.DIMENSION_MISMATCH` on a mismatch; missing optional drivers return `HaiVecdbError.DRIVER_NOT_FOUND`.
+
+## Error handling
+
+All operations return `HaiResult<T>`; check `result.success` for success or failure.
+
+```ts
+const result = await vecdb.collection.create('docs', { dimension: 1536 })
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiVecdbError.NOT_INITIALIZED.code:
+      // 请先调用 vecdb.init()
+      break
+    case HaiVecdbError.COLLECTION_ALREADY_EXISTS.code:
+      // 集合已存在
+      break
+    case HaiVecdbError.CONNECTION_FAILED.code:
+      // 连接失败
+      break
+  }
+}
+```
+
+## Tests
+
+```bash
+pnpm --filter @h-ai/vecdb test
+```
+
+> pgvector / Qdrant tests require Docker.
+
+## License
+
+Apache-2.0

package/README.ja.md

@@ -0,0 +1,145 @@
+# @h-ai/vecdb
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
+
+共通の `vecdb` オブジェクトで LanceDB、pgvector、Qdrant、Chroma を操作するベクトルデータベースモジュールです。
+
+## 対応ベクトルデータベース
+
+- LanceDB（組み込み型、ローカルファイル保存、設定不要）
+- pgvector（PostgreSQL + pgvector 拡張）
+- Qdrant（高性能ベクトル検索エンジン）
+- Chroma（組み込みモードでローカルサービスを自動起動、または既存サービスへ直接接続）
+
+## クイックスタート
+
+```ts
+import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
+
+// 初始化（LanceDB）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// 创建集合
+await vecdb.collection.create('docs', { dimension: 1536 })
+
+// 插入向量
+await vecdb.vector.insert('docs', [
+  { id: 'doc-1', vector: Array.from({ length: 1536 }).fill(0.1), content: '文档内容', metadata: { source: 'wiki' } },
+])
+
+// 搜索
+const searchResult = await vecdb.vector.search('docs', Array.from({ length: 1536 }).fill(0.2), { topK: 5, minScore: 0.7 })
+if (searchResult.success) {
+  for (const item of searchResult.data) {
+    // item.id, item.score, item.content
+  }
+}
+
+// 关闭
+const closeResult = await vecdb.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
+```
+
+## 設定
+
+```ts
+// LanceDB（默认，嵌入式本地存储）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// pgvector（连接字符串）
+await vecdb.init({ type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' })
+
+// pgvector（分字段）
+await vecdb.init({
+  type: 'pgvector',
+  host: 'localhost',
+  port: 5432,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  indexType: 'hnsw',
+  tablePrefix: 'vec_',
+})
+
+// Qdrant
+await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333', apiKey: 'optional-key' })
+
+// Chroma（嵌入式：自动拉起本地 `chroma run` 服务并持久化到 path）
+await vecdb.init({ type: 'chroma', path: './data/chroma' })
+
+// Chroma（直连已有服务，不拉起进程）
+await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
+```
+
+> Node 版の Chroma は HTTP クライアントのみで、プロセス内の組み込み DB はありません。組み込みモードでは `vecdb.init` が
+> `serverCommand`（既定は `chromadb` パッケージの `chroma`）でローカルサービスを起動し、`vecdb.close` が
+> そのプロセスを停止します。任意依存の `chromadb` をインストールしてください。コマンドが利用できない場合、`init` は `CONNECTION_FAILED` を返します。
+
+### 操作ログ
+
+ベクトルデータベース設定の `operationLog` で操作ログを有効にできます。ログはコレクション・ベクトル操作が実際の Provider に渡る前に出力され、`vecdb-main.ts` で一括ラップはしません。
+
+```yaml
+# config/_vecdb.yml
+type: lancedb
+path: ./data/vecdb
+operationLog:
+  read: false # collection.exists/info/list, vector.search/count
+  write: false # collection.create/drop, vector.insert/upsert/delete
+  maxLength: 1000 # 参数序列化后的最大输出长度，超出会截断
+  level: debug # info | debug | trace，默认 debug
+```
+
+```ts
+await vecdb.init({
+  type: 'lancedb',
+  path: './data/vecdb',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+> 注：`vecdb.config` は**機密情報をマスクした設定スナップショット**を返します。接続文字列のユーザー名・パスワード、個別の `password`、`apiKey` は `[REDACTED]` に置換されます。
+
+> 動作：空の一括 `insert/upsert/delete` は何もしません。書き込み・検索時にはベクトル次元を検証し、不一致なら `HaiVecdbError.DIMENSION_MISMATCH`、任意ドライバーの不足なら `HaiVecdbError.DRIVER_NOT_FOUND` を返します。
+
+## エラー処理
+
+すべての操作は `HaiResult<T>` を返し、`result.success` で成功・失敗を判定します。
+
+```ts
+const result = await vecdb.collection.create('docs', { dimension: 1536 })
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiVecdbError.NOT_INITIALIZED.code:
+      // 请先调用 vecdb.init()
+      break
+    case HaiVecdbError.COLLECTION_ALREADY_EXISTS.code:
+      // 集合已存在
+      break
+    case HaiVecdbError.CONNECTION_FAILED.code:
+      // 连接失败
+      break
+  }
+}
+```
+
+## テスト
+
+```bash
+pnpm --filter @h-ai/vecdb test
+```
+
+> pgvector / Qdrant のテストには Docker が必要です。
+
+## License
+
+Apache-2.0

package/README.md

@@ -1,5 +1,9 @@
 # @h-ai/vecdb
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
 向量数据库模块，通过统一的 `vecdb` 对象访问 LanceDB、pgvector、Qdrant、Chroma。
 
 ## 支持的向量数据库

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/vecdb",
   "type": "module",
-  "version": "0.1.0-alpha.56",
+  "version": "0.1.0-alpha.57",
   "description": "Hai Framework vector database module for LanceDB, pgvector, Qdrant, and Chroma.",
   "license": "Apache-2.0",
   "exports": {
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@h-ai/core": "0.1.0-alpha.56"
+    "@h-ai/core": "0.1.0-alpha.57"
   },
   "optionalDependencies": {
     "@lancedb/lancedb": "^0.27.2",