@agentuity/vector 1.0.54

package/AGENTS.md

@@ -0,0 +1,43 @@
+# Agent Guidelines for @agentuity/vector
+
+## Package Overview
+
+Standalone package for the Agentuity Vector storage service. Provides a simple, ergonomic client for storing and searching vector embeddings.
+
+## Commands
+
+- **Build**: `bun run build`
+- **Typecheck**: `bun run typecheck`
+- **Clean**: `rm -rf dist`
+
+## Architecture
+
+- **Runtime**: Node.js and Bun compatible
+- **Exports**: VectorClient and all types from @agentuity/core/vector
+- **Dependencies**: @agentuity/core, zod
+
+## Usage
+
+```typescript
+import { VectorClient } from '@agentuity/vector';
+
+const client = new VectorClient();
+
+// Upsert vectors with automatic embedding
+await client.upsert('products', {
+  key: 'chair-001',
+  document: 'Comfortable office chair with lumbar support',
+  metadata: { category: 'furniture' }
+});
+
+// Search for similar vectors
+const results = await client.search('products', {
+  query: 'office seating',
+  limit: 5
+});
+```
+
+## Publishing
+
+1. Run `bun run build`
+2. Must publish **after** @agentuity/core

package/README.md

@@ -0,0 +1,56 @@
+# @agentuity/vector
+
+A standalone package for the Agentuity Vector storage service.
+
+## Installation
+
+```bash
+npm install @agentuity/vector
+```
+
+## Quick Start
+
+```typescript
+import { VectorClient } from '@agentuity/vector';
+
+const client = new VectorClient();
+
+// Upsert vectors with automatic embedding
+await client.upsert('products', {
+  key: 'chair-001',
+  document: 'Comfortable office chair with lumbar support',
+  metadata: { category: 'furniture', price: 299 }
+});
+
+// Search for similar vectors
+const results = await client.search('products', {
+  query: 'office seating',
+  limit: 5,
+  similarity: 0.7
+});
+
+for (const result of results) {
+  console.log(`${result.key}: ${result.similarity * 100}% match`);
+}
+```
+
+## Configuration
+
+```typescript
+const client = new VectorClient({
+  apiKey: 'your-api-key',
+  url: 'https://api.agentuity.com',
+});
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTUITY_SDK_KEY` | API key for authentication | Required |
+| `AGENTUITY_REGION` | Region for API endpoints | `usc` |
+| `AGENTUITY_VECTOR_URL` | Override Vector API URL | Auto-detected |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+export { VectorStorageService, VectorStorage, type VectorUpsertParams, type VectorUpsertBase, type VectorUpsertEmbeddings, type VectorUpsertText, type VectorUpsertResult, type VectorSearchParams, type VectorSearchResult, type VectorSearchResultWithDocument, type VectorResult, type VectorResultFound, type VectorResultNotFound, type VectorNamespaceStats, type VectorNamespaceStatsWithSamples, type VectorItemStats, type VectorGetAllStatsParams, type VectorStatsPaginated, type VectorSortField, VECTOR_MIN_TTL_SECONDS, VECTOR_MAX_TTL_SECONDS, VECTOR_DEFAULT_TTL_SECONDS, VectorUpsertBaseSchema, VectorUpsertEmbeddingsSchema, VectorUpsertTextSchema, VectorUpsertParamsSchema, VectorSearchParamsSchema, VectorSearchResultSchema, VectorSearchResultWithDocumentSchema, VectorUpsertResultSchema, VectorResultFoundSchema, VectorResultNotFoundSchema, VectorResultSchema, VectorNamespaceStatsSchema, VectorNamespaceStatsWithSamplesSchema, VectorItemStatsSchema, VectorGetAllStatsParamsSchema, VectorStatsPaginatedSchema, VectorSortFieldSchema, } from '@agentuity/core/vector';
+import { VectorStorageService, type VectorUpsertParams, type VectorSearchParams, type VectorResult, type VectorSearchResult, type VectorSearchResultWithDocument, type VectorUpsertResult } from '@agentuity/core/vector';
+import { type Logger } from '@agentuity/server';
+import { z } from 'zod';
+export declare const VectorClientOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodString>;
+    logger: z.ZodOptional<z.ZodCustom<Logger, Logger>>;
+}, z.core.$strip>;
+export type VectorClientOptions = z.infer<typeof VectorClientOptionsSchema>;
+export declare class VectorClient {
+    #private;
+    constructor(options?: VectorClientOptions);
+    upsert(name: string, ...documents: VectorUpsertParams[]): Promise<VectorUpsertResult[]>;
+    get<T extends Record<string, unknown> = Record<string, unknown>>(name: string, key: string): Promise<VectorResult<T>>;
+    getMany<T extends Record<string, unknown> = Record<string, unknown>>(name: string, ...keys: string[]): Promise<Map<string, VectorSearchResultWithDocument<T>>>;
+    search<T extends Record<string, unknown> = Record<string, unknown>>(name: string, params: VectorSearchParams<T>): Promise<VectorSearchResult<T>[]>;
+    delete(name: string, ...keys: string[]): Promise<number>;
+    exists(name: string): Promise<boolean>;
+    getStats(name: string): Promise<{
+        sum: number;
+        count: number;
+        createdAt?: number | undefined;
+        lastUsed?: number | undefined;
+        internal?: boolean | undefined;
+        sampledResults?: Record<string, {
+            size: number;
+            firstUsed: number;
+            lastUsed: number;
+            embedding?: number[] | undefined;
+            document?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            count?: number | undefined;
+            expiresAt?: string | undefined;
+        }> | undefined;
+    }>;
+    getAllStats(params?: Parameters<VectorStorageService['getAllStats']>[0]): Promise<Record<string, {
+        sum: number;
+        count: number;
+        createdAt?: number | undefined;
+        lastUsed?: number | undefined;
+        internal?: boolean | undefined;
+    }> | {
+        namespaces: Record<string, {
+            sum: number;
+            count: number;
+            createdAt?: number | undefined;
+            lastUsed?: number | undefined;
+            internal?: boolean | undefined;
+        }>;
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    }>;
+    getNamespaces(): Promise<string[]>;
+    deleteNamespace(name: string): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,8BAA8B,EACnC,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,+BAA+B,EACpC,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,oCAAoC,EACpC,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,EAC1B,qCAAqC,EACrC,qBAAqB,EACrB,6BAA6B,EAC7B,0BAA0B,EAC1B,qBAAqB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACN,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,8BAA8B,EACnC,KAAK,kBAAkB,EACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAgD,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI9F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,eAAO,MAAM,yBAAyB;;;;;iBAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,qBAAa,YAAY;;gBAGZ,OAAO,GAAE,mBAAwB;IAoBvC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAIvF,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAIrB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,IAAI,EAAE,MAAM,EACZ,GAAG,IAAI,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC,CAAC,CAAC,CAAC;IAIpD,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvE,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;IAI7B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAIxD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,QAAQ,CAAC,IAAI,EAAE,MAAM;;;;;;;;;;;;;;;;;IAIrB,WAAW,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;IAIvE,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlD"}

package/dist/index.js

@@ -0,0 +1,64 @@
+export { VectorStorageService, VECTOR_MIN_TTL_SECONDS, VECTOR_MAX_TTL_SECONDS, VECTOR_DEFAULT_TTL_SECONDS, VectorUpsertBaseSchema, VectorUpsertEmbeddingsSchema, VectorUpsertTextSchema, VectorUpsertParamsSchema, VectorSearchParamsSchema, VectorSearchResultSchema, VectorSearchResultWithDocumentSchema, VectorUpsertResultSchema, VectorResultFoundSchema, VectorResultNotFoundSchema, VectorResultSchema, VectorNamespaceStatsSchema, VectorNamespaceStatsWithSamplesSchema, VectorItemStatsSchema, VectorGetAllStatsParamsSchema, VectorStatsPaginatedSchema, VectorSortFieldSchema, } from '@agentuity/core/vector';
+import { VectorStorageService, } from '@agentuity/core/vector';
+import { createServerFetchAdapter, buildClientHeaders } from '@agentuity/server';
+import { createMinimalLogger } from '@agentuity/core';
+import { getEnv } from '@agentuity/core';
+import { getServiceUrls } from '@agentuity/core/config';
+import { z } from 'zod';
+const isLogger = (val) => typeof val === 'object' &&
+    val !== null &&
+    ['info', 'warn', 'error', 'debug', 'trace'].every((m) => typeof val[m] === 'function');
+export const VectorClientOptionsSchema = z.object({
+    apiKey: z.string().optional().describe('API key for authentication'),
+    url: z.string().optional().describe('Base URL for the Vector API'),
+    orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
+    logger: z.custom(isLogger).optional().describe('Custom logger instance'),
+});
+export class VectorClient {
+    #service;
+    constructor(options = {}) {
+        const validatedOptions = VectorClientOptionsSchema.parse(options);
+        const apiKey = validatedOptions.apiKey || getEnv('AGENTUITY_SDK_KEY') || getEnv('AGENTUITY_CLI_KEY');
+        const region = getEnv('AGENTUITY_REGION') ?? 'usc';
+        const serviceUrls = getServiceUrls(region);
+        const url = validatedOptions.url || getEnv('AGENTUITY_VECTOR_URL') || serviceUrls.vector;
+        const logger = validatedOptions.logger ?? createMinimalLogger();
+        const headers = buildClientHeaders({
+            apiKey,
+            orgId: validatedOptions.orgId,
+        });
+        const adapter = createServerFetchAdapter({ headers }, logger);
+        this.#service = new VectorStorageService(url, adapter);
+    }
+    async upsert(name, ...documents) {
+        return this.#service.upsert(name, ...documents);
+    }
+    async get(name, key) {
+        return this.#service.get(name, key);
+    }
+    async getMany(name, ...keys) {
+        return this.#service.getMany(name, ...keys);
+    }
+    async search(name, params) {
+        return this.#service.search(name, params);
+    }
+    async delete(name, ...keys) {
+        return this.#service.delete(name, ...keys);
+    }
+    async exists(name) {
+        return this.#service.exists(name);
+    }
+    async getStats(name) {
+        return this.#service.getStats(name);
+    }
+    async getAllStats(params) {
+        return this.#service.getAllStats(params);
+    }
+    async getNamespaces() {
+        return this.#service.getNamespaces();
+    }
+    async deleteNamespace(name) {
+        return this.#service.deleteNamespace(name);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EAmBpB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,oCAAoC,EACpC,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,EAC1B,qCAAqC,EACrC,qBAAqB,EACrB,6BAA6B,EAC7B,0BAA0B,EAC1B,qBAAqB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACN,oBAAoB,GAOpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAe,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,QAAQ,GAAG,CAAC,GAAY,EAAiB,EAAE,CAChD,OAAO,GAAG,KAAK,QAAQ;IACvB,GAAG,KAAK,IAAI;IACZ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,OAAQ,GAA+B,CAAC,CAAC,CAAC,KAAK,UAAU,CAChE,CAAC;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACpE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAClE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IACpF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAS,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;CAChF,CAAC,CAAC;AAGH,MAAM,OAAO,YAAY;IACf,QAAQ,CAAuB;IAExC,YAAY,UAA+B,EAAE;QAC5C,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClE,MAAM,MAAM,GACX,gBAAgB,CAAC,MAAM,IAAI,MAAM,CAAC,mBAAmB,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACvF,MAAM,MAAM,GAAG,MAAM,CAAC,kBAAkB,CAAC,IAAI,KAAK,CAAC;QACnD,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QAE3C,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,IAAI,MAAM,CAAC,sBAAsB,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC;QAEzF,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;QAEhE,MAAM,OAAO,GAAG,kBAAkB,CAAC;YAClC,MAAM;YACN,KAAK,EAAE,gBAAgB,CAAC,KAAK;SAC7B,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9D,IAAI,CAAC,QAAQ,GAAG,IAAI,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,GAAG,SAA+B;QAC5D,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,GAAG,CACR,IAAY,EACZ,GAAW;QAEX,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,OAAO,CACZ,IAAY,EACZ,GAAG,IAAc;QAEjB,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,MAAM,CACX,IAAY,EACZ,MAA6B;QAE7B,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,GAAG,IAAc;QAC3C,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,MAA2D;QAC5E,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,aAAa;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,IAAY;QACjC,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;CACD"}

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@agentuity/vector",
+	"version": "1.0.54",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"AGENTS.md",
+		"README.md",
+		"src",
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"build": "bunx tsc --build --force",
+		"typecheck": "bunx tsc --noEmit",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"dependencies": {
+		"@agentuity/core": "1.0.54",
+		"@agentuity/server": "1.0.54",
+		"zod": "^4.3.5"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/node": "^22.0.0",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false
+}

package/src/index.ts

@@ -0,0 +1,144 @@
+export {
+	VectorStorageService,
+	VectorStorage,
+	type VectorUpsertParams,
+	type VectorUpsertBase,
+	type VectorUpsertEmbeddings,
+	type VectorUpsertText,
+	type VectorUpsertResult,
+	type VectorSearchParams,
+	type VectorSearchResult,
+	type VectorSearchResultWithDocument,
+	type VectorResult,
+	type VectorResultFound,
+	type VectorResultNotFound,
+	type VectorNamespaceStats,
+	type VectorNamespaceStatsWithSamples,
+	type VectorItemStats,
+	type VectorGetAllStatsParams,
+	type VectorStatsPaginated,
+	type VectorSortField,
+	VECTOR_MIN_TTL_SECONDS,
+	VECTOR_MAX_TTL_SECONDS,
+	VECTOR_DEFAULT_TTL_SECONDS,
+	VectorUpsertBaseSchema,
+	VectorUpsertEmbeddingsSchema,
+	VectorUpsertTextSchema,
+	VectorUpsertParamsSchema,
+	VectorSearchParamsSchema,
+	VectorSearchResultSchema,
+	VectorSearchResultWithDocumentSchema,
+	VectorUpsertResultSchema,
+	VectorResultFoundSchema,
+	VectorResultNotFoundSchema,
+	VectorResultSchema,
+	VectorNamespaceStatsSchema,
+	VectorNamespaceStatsWithSamplesSchema,
+	VectorItemStatsSchema,
+	VectorGetAllStatsParamsSchema,
+	VectorStatsPaginatedSchema,
+	VectorSortFieldSchema,
+} from '@agentuity/core/vector';
+
+import {
+	VectorStorageService,
+	type VectorUpsertParams,
+	type VectorSearchParams,
+	type VectorResult,
+	type VectorSearchResult,
+	type VectorSearchResultWithDocument,
+	type VectorUpsertResult,
+} from '@agentuity/core/vector';
+import { createServerFetchAdapter, buildClientHeaders, type Logger } from '@agentuity/server';
+import { createMinimalLogger } from '@agentuity/core';
+import { getEnv } from '@agentuity/core';
+import { getServiceUrls } from '@agentuity/core/config';
+import { z } from 'zod';
+
+const isLogger = (val: unknown): val is Logger =>
+	typeof val === 'object' &&
+	val !== null &&
+	['info', 'warn', 'error', 'debug', 'trace'].every(
+		(m) => typeof (val as Record<string, unknown>)[m] === 'function'
+	);
+
+export const VectorClientOptionsSchema = z.object({
+	apiKey: z.string().optional().describe('API key for authentication'),
+	url: z.string().optional().describe('Base URL for the Vector API'),
+	orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
+	logger: z.custom<Logger>(isLogger).optional().describe('Custom logger instance'),
+});
+export type VectorClientOptions = z.infer<typeof VectorClientOptionsSchema>;
+
+export class VectorClient {
+	readonly #service: VectorStorageService;
+
+	constructor(options: VectorClientOptions = {}) {
+		const validatedOptions = VectorClientOptionsSchema.parse(options);
+		const apiKey =
+			validatedOptions.apiKey || getEnv('AGENTUITY_SDK_KEY') || getEnv('AGENTUITY_CLI_KEY');
+		const region = getEnv('AGENTUITY_REGION') ?? 'usc';
+		const serviceUrls = getServiceUrls(region);
+
+		const url = validatedOptions.url || getEnv('AGENTUITY_VECTOR_URL') || serviceUrls.vector;
+
+		const logger = validatedOptions.logger ?? createMinimalLogger();
+
+		const headers = buildClientHeaders({
+			apiKey,
+			orgId: validatedOptions.orgId,
+		});
+
+		const adapter = createServerFetchAdapter({ headers }, logger);
+		this.#service = new VectorStorageService(url, adapter);
+	}
+
+	async upsert(name: string, ...documents: VectorUpsertParams[]): Promise<VectorUpsertResult[]> {
+		return this.#service.upsert(name, ...documents);
+	}
+
+	async get<T extends Record<string, unknown> = Record<string, unknown>>(
+		name: string,
+		key: string
+	): Promise<VectorResult<T>> {
+		return this.#service.get(name, key);
+	}
+
+	async getMany<T extends Record<string, unknown> = Record<string, unknown>>(
+		name: string,
+		...keys: string[]
+	): Promise<Map<string, VectorSearchResultWithDocument<T>>> {
+		return this.#service.getMany(name, ...keys);
+	}
+
+	async search<T extends Record<string, unknown> = Record<string, unknown>>(
+		name: string,
+		params: VectorSearchParams<T>
+	): Promise<VectorSearchResult<T>[]> {
+		return this.#service.search(name, params);
+	}
+
+	async delete(name: string, ...keys: string[]): Promise<number> {
+		return this.#service.delete(name, ...keys);
+	}
+
+	async exists(name: string): Promise<boolean> {
+		return this.#service.exists(name);
+	}
+
+	async getStats(name: string) {
+		return this.#service.getStats(name);
+	}
+
+	async getAllStats(params?: Parameters<VectorStorageService['getAllStats']>[0]) {
+		return this.#service.getAllStats(params);
+	}
+
+	async getNamespaces(): Promise<string[]> {
+		return this.#service.getNamespaces();
+	}
+
+	async deleteNamespace(name: string): Promise<void> {
+		return this.#service.deleteNamespace(name);
+	}
+}