@agentuity/core 1.0.32 → 1.0.34

package/src/services/{vector.ts → vector/service.ts}

@@ -1,8 +1,9 @@
-import { FetchAdapter } from './adapter.ts';
-import { buildUrl, toServiceException } from './_util.ts';
-import type { ListParams } from './pagination.ts';
-import { safeStringify } from '../json.ts';
-import { StructuredError } from '../error.ts';
+import { FetchAdapter } from '../adapter.ts';
+import { buildUrl, toServiceException } from '../_util.ts';
+import { ListParamsSchema } from '../pagination.ts';
+import { safeStringify } from '../../json.ts';
+import { StructuredError } from '../../error.ts';
+import { z } from 'zod';
 
 /**
  * Minimum TTL value in seconds (1 minute)
@@ -22,16 +23,20 @@ export const VECTOR_DEFAULT_TTL_SECONDS = 2592000;
 /**
  * Base properties shared by all vector upsert operations
  */
-export interface VectorUpsertBase {
+export const VectorUpsertBaseSchema = z.object({
 	/**
 	 * the key of the vector object which can be used as a reference. the value of this key is opaque to the vector storage.
 	 */
-	key: string;
+	key: z
+		.string()
+		.describe(
+			'the key of the vector object which can be used as a reference. the value of this key is opaque to the vector storage.'
+		),
 
 	/**
 	 * the metadata to upsert
 	 */
-	metadata?: Record<string, unknown>;
+	metadata: z.record(z.string(), z.unknown()).optional().describe('the metadata to upsert'),
 
 	/**
 	 * Time-to-live in seconds for the vector. Controls when the vector expires and is automatically deleted.
@@ -45,173 +50,254 @@ export interface VectorUpsertBase {
 	 *
 	 * @default 2592000 (30 days)
 	 */
-	ttl?: number | null;
-}
+	ttl: z
+		.number()
+		.nullable()
+		.optional()
+		.describe(
+			'Time-to-live in seconds for the vector. Controls when the vector expires and is automatically deleted.'
+		),
+});
+
+export type VectorUpsertBase = z.infer<typeof VectorUpsertBaseSchema>;
 
 /**
  * Upsert using pre-computed embeddings
  */
-export interface VectorUpsertEmbeddings extends VectorUpsertBase {
+export const VectorUpsertEmbeddingsSchema = VectorUpsertBaseSchema.extend({
 	/**
 	 * the embeddings to upsert
 	 */
-	embeddings: Array<number>;
-	document?: never;
-}
+	embeddings: z.array(z.number()).describe('the embeddings to upsert'),
+	document: z.never().optional(),
+});
+
+export type VectorUpsertEmbeddings = z.infer<typeof VectorUpsertEmbeddingsSchema>;
 
 /**
  * Upsert using text that will be converted to embeddings
  */
-export interface VectorUpsertText extends VectorUpsertBase {
+export const VectorUpsertTextSchema = VectorUpsertBaseSchema.extend({
 	/**
 	 * the text to use for the embedding
 	 */
-	document: string;
-	embeddings?: never;
-}
+	document: z.string().describe('the text to use for the embedding'),
+	embeddings: z.never().optional(),
+});
+
+export type VectorUpsertText = z.infer<typeof VectorUpsertTextSchema>;
 
 /**
  * Parameters for upserting a vector
  */
 export type VectorUpsertParams = VectorUpsertEmbeddings | VectorUpsertText;
+export const VectorUpsertParamsSchema = z.discriminatedUnion('document', [
+	VectorUpsertTextSchema,
+	VectorUpsertEmbeddingsSchema.extend({ document: z.undefined().optional() }),
+]);
 
 /**
  * Parameters for searching vectors
  */
-export interface VectorSearchParams<T extends Record<string, unknown> = Record<string, unknown>> {
-	/**
-	 * The text query to search for in the vector storage. This will be converted to embeddings
-	 * and used to find semantically similar documents.
-	 *
-	 * @example "comfortable office chair"
-	 * @example "machine learning algorithms"
-	 */
+export const VectorSearchParamsSchema = <T extends z.ZodTypeAny>(metadataSchema: T) =>
+	z.object({
+		/**
+		 * The text query to search for in the vector storage. This will be converted to embeddings
+		 * and used to find semantically similar documents.
+		 *
+		 * @example "comfortable office chair"
+		 * @example "machine learning algorithms"
+		 */
+		query: z
+			.string()
+			.describe(
+				'The text query to search for in the vector storage. This will be converted to embeddings and used to find semantically similar documents.'
+			),
+
+		/**
+		 * Maximum number of search results to return. If not specified, the server default will be used.
+		 * Must be a positive integer.
+		 *
+		 * @default 10
+		 * @example 5
+		 * @example 20
+		 */
+		limit: z
+			.number()
+			.optional()
+			.describe(
+				'Maximum number of search results to return. If not specified, the server default will be used.'
+			),
+
+		/**
+		 * Minimum similarity threshold for results. Only vectors with similarity scores greater than or equal
+		 * to this value will be returned. Value must be between 0.0 and 1.0, where 1.0 means exact match
+		 * and 0.0 means no similarity requirement.
+		 *
+		 * @minimum 0.0
+		 * @maximum 1.0
+		 * @example 0.7
+		 * @example 0.5
+		 */
+		similarity: z
+			.number()
+			.min(0)
+			.max(1)
+			.optional()
+			.describe(
+				'Minimum similarity threshold for results. Only vectors with similarity scores greater than or equal to this value will be returned.'
+			),
+
+		/**
+		 * Metadata filters to apply to the search. Only vectors whose metadata matches all specified
+		 * key-value pairs will be included in results. Must be a valid JSON object if provided.
+		 *
+		 * @example { category: "furniture", inStock: true }
+		 * @example { userId: "123", type: "product" }
+		 */
+		metadata: metadataSchema
+			.optional()
+			.describe(
+				'Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results.'
+			),
+	});
+
+export type VectorSearchParams<T extends Record<string, unknown> = Record<string, unknown>> = {
 	query: string;
-
-	/**
-	 * Maximum number of search results to return. If not specified, the server default will be used.
-	 * Must be a positive integer.
-	 *
-	 * @default 10
-	 * @example 5
-	 * @example 20
-	 */
 	limit?: number;
-
-	/**
-	 * Minimum similarity threshold for results. Only vectors with similarity scores greater than or equal
-	 * to this value will be returned. Value must be between 0.0 and 1.0, where 1.0 means exact match
-	 * and 0.0 means no similarity requirement.
-	 *
-	 * @minimum 0.0
-	 * @maximum 1.0
-	 * @example 0.7
-	 * @example 0.5
-	 */
 	similarity?: number;
-
-	/**
-	 * Metadata filters to apply to the search. Only vectors whose metadata matches all specified
-	 * key-value pairs will be included in results. Must be a valid JSON object if provided.
-	 *
-	 * @example { category: "furniture", inStock: true }
-	 * @example { userId: "123", type: "product" }
-	 */
 	metadata?: T;
-}
+};
 
 /**
  * Result of a vector search operation with optional type-safe metadata
  */
-export interface VectorSearchResult<T extends Record<string, unknown> = Record<string, unknown>> {
-	/**
-	 * the unique id of the object in vector storage
-	 */
+export const VectorSearchResultSchema = <T extends z.ZodTypeAny>(metadataSchema: T) =>
+	z.object({
+		/**
+		 * the unique id of the object in vector storage
+		 */
+		id: z.string().describe('the unique id of the object in vector storage'),
+
+		/**
+		 * the key used when the vector object was added to vector storage
+		 */
+		key: z.string().describe('the key used when the vector object was added to vector storage'),
+
+		/**
+		 * the metadata of the vector object when it was stored
+		 */
+		metadata: metadataSchema
+			.optional()
+			.describe('the metadata of the vector object when it was stored'),
+
+		/**
+		 * the distance of the vector object from the query from 0-1. The larger the number, the more similar the vector object is to the query.
+		 */
+		similarity: z
+			.number()
+			.describe(
+				'the distance of the vector object from the query from 0-1. The larger the number, the more similar the vector object is to the query.'
+			),
+
+		/**
+		 * the expiration time of the vector as an ISO 8601 timestamp.
+		 * undefined if the vector does not expire.
+		 */
+		expiresAt: z
+			.string()
+			.optional()
+			.describe('the expiration time of the vector as an ISO 8601 timestamp.'),
+	});
+
+export type VectorSearchResult<T extends Record<string, unknown> = Record<string, unknown>> = {
 	id: string;
-
-	/**
-	 * the key used when the vector object was added to vector storage
-	 */
 	key: string;
-
-	/**
-	 * the metadata of the vector object when it was stored
-	 */
 	metadata?: T;
-
-	/**
-	 * the distance of the vector object from the query from 0-1. The larger the number, the more similar the vector object is to the query.
-	 */
 	similarity: number;
-
-	/**
-	 * the expiration time of the vector as an ISO 8601 timestamp.
-	 * undefined if the vector does not expire.
-	 */
 	expiresAt?: string;
-}
+};
 
 /**
  * Extended search result that includes the document and embeddings
  */
-export interface VectorSearchResultWithDocument<
+export const VectorSearchResultWithDocumentSchema = <T extends z.ZodTypeAny>(metadataSchema: T) =>
+	VectorSearchResultSchema(metadataSchema).extend({
+		/**
+		 * the document that was used to create the vector object
+		 */
+		document: z
+			.string()
+			.optional()
+			.describe('the document that was used to create the vector object'),
+
+		/**
+		 * the embeddings of the vector object
+		 */
+		embeddings: z.array(z.number()).optional().describe('the embeddings of the vector object'),
+	});
+
+export type VectorSearchResultWithDocument<
 	T extends Record<string, unknown> = Record<string, unknown>,
-> extends VectorSearchResult<T> {
-	/**
-	 * the document that was used to create the vector object
-	 */
+> = VectorSearchResult<T> & {
 	document?: string;
-
-	/**
-	 * the embeddings of the vector object
-	 */
 	embeddings?: Array<number>;
-}
+};
 
 /**
  * Result of a vector upsert operation
  */
-export interface VectorUpsertResult {
+export const VectorUpsertResultSchema = z.object({
 	/**
 	 * the key from the original upsert document
 	 */
-	key: string;
+	key: z.string().describe('the key from the original upsert document'),
 
 	/**
 	 * the generated id for this vector in storage
 	 */
-	id: string;
-}
+	id: z.string().describe('the generated id for this vector in storage'),
+});
+
+export type VectorUpsertResult = z.infer<typeof VectorUpsertResultSchema>;
 
 /**
  * Result when a vector is found by key
  */
-export interface VectorResultFound<T extends Record<string, unknown> = Record<string, unknown>> {
-	/**
-	 * the vector data
-	 */
+export const VectorResultFoundSchema = <T extends z.ZodTypeAny>(metadataSchema: T) =>
+	z.object({
+		/**
+		 * the vector data
+		 */
+		data: VectorSearchResultWithDocumentSchema(metadataSchema).describe('the vector data'),
+
+		/**
+		 * the vector was found
+		 */
+		exists: z.literal(true).describe('the vector was found'),
+	});
+
+export type VectorResultFound<T extends Record<string, unknown> = Record<string, unknown>> = {
 	data: VectorSearchResultWithDocument<T>;
-
-	/**
-	 * the vector was found
-	 */
 	exists: true;
-}
+};
 
 /**
  * Result when a vector is not found by key
  */
-export interface VectorResultNotFound {
+export const VectorResultNotFoundSchema = z.object({
 	/**
 	 * no data available
 	 */
-	data: never;
+	data: z.never().describe('no data available'),
 
 	/**
 	 * the vector was not found
 	 */
-	exists: false;
-}
+	exists: z.literal(false).describe('the vector was not found'),
+});
+
+export type VectorResultNotFound = z.infer<typeof VectorResultNotFoundSchema>;
 
 /**
  * Result of a get operation
@@ -220,125 +306,162 @@ export type VectorResult<T extends Record<string, unknown> = Record<string, unkn
 	| VectorResultFound<T>
 	| VectorResultNotFound;
 
+export const VectorResultSchema = <T extends z.ZodTypeAny>(metadataSchema: T) =>
+	z.discriminatedUnion('exists', [
+		VectorResultFoundSchema(metadataSchema),
+		VectorResultNotFoundSchema,
+	]);
+
 /**
  * Statistics for a vector namespace
  */
-export interface VectorNamespaceStats {
+export const VectorNamespaceStatsSchema = z.object({
 	/**
 	 * Total size in bytes
 	 */
-	sum: number;
+	sum: z.number().describe('Total size in bytes'),
 
 	/**
 	 * Number of vectors in the namespace
 	 */
-	count: number;
+	count: z.number().describe('Number of vectors in the namespace'),
 
 	/**
 	 * Unix timestamp (milliseconds) when the namespace was created
 	 */
-	createdAt?: number;
+	createdAt: z
+		.number()
+		.optional()
+		.describe('Unix timestamp (milliseconds) when the namespace was created'),
 
 	/**
 	 * Unix timestamp (milliseconds) when the namespace was last used
 	 */
-	lastUsed?: number;
-}
+	lastUsed: z
+		.number()
+		.optional()
+		.describe('Unix timestamp (milliseconds) when the namespace was last used'),
+});
+
+export type VectorNamespaceStats = z.infer<typeof VectorNamespaceStatsSchema>;
 
 /**
  * Statistics for an individual vector item
  */
-export interface VectorItemStats {
+export const VectorItemStatsSchema = z.object({
 	/**
 	 * The embedding vector
 	 */
-	embedding?: number[];
+	embedding: z.array(z.number()).optional().describe('The embedding vector'),
 
 	/**
 	 * The original document text
 	 */
-	document?: string;
+	document: z.string().optional().describe('The original document text'),
 
 	/**
 	 * Size in bytes
 	 */
-	size: number;
+	size: z.number().describe('Size in bytes'),
 
 	/**
 	 * Metadata associated with the vector
 	 */
-	metadata?: Record<string, unknown>;
+	metadata: z
+		.record(z.string(), z.unknown())
+		.optional()
+		.describe('Metadata associated with the vector'),
 
 	/**
 	 * Unix timestamp (milliseconds) when the vector was first accessed
 	 */
-	firstUsed: number;
+	firstUsed: z
+		.number()
+		.describe('Unix timestamp (milliseconds) when the vector was first accessed'),
 
 	/**
 	 * Unix timestamp (milliseconds) when the vector was last accessed
 	 */
-	lastUsed: number;
+	lastUsed: z.number().describe('Unix timestamp (milliseconds) when the vector was last accessed'),
 
 	/**
 	 * Number of times the vector was accessed.
 	 * Note: This is only tracked in cloud storage; local development returns undefined.
 	 */
-	count?: number;
+	count: z.number().optional().describe('Number of times the vector was accessed.'),
 
 	/**
 	 * the expiration time of the vector as an ISO 8601 timestamp.
 	 * undefined if the vector does not expire.
 	 */
-	expiresAt?: string;
-}
+	expiresAt: z
+		.string()
+		.optional()
+		.describe('the expiration time of the vector as an ISO 8601 timestamp.'),
+});
+
+export type VectorItemStats = z.infer<typeof VectorItemStatsSchema>;
 
 /**
  * Namespace statistics with sampled vector results
  */
-export interface VectorNamespaceStatsWithSamples extends VectorNamespaceStats {
+export const VectorNamespaceStatsWithSamplesSchema = VectorNamespaceStatsSchema.extend({
 	/**
 	 * A sample of vectors in the namespace (up to 20)
 	 */
-	sampledResults?: Record<string, VectorItemStats>;
-}
+	sampledResults: z
+		.record(z.string(), VectorItemStatsSchema)
+		.optional()
+		.describe('A sample of vectors in the namespace (up to 20)'),
+});
 
-export type VectorSortField = 'name' | 'size' | 'records' | 'created' | 'lastUsed';
+export type VectorNamespaceStatsWithSamples = z.infer<typeof VectorNamespaceStatsWithSamplesSchema>;
+
+export const VectorSortFieldSchema = z.enum(['name', 'size', 'records', 'created', 'lastUsed']);
+
+export type VectorSortField = z.infer<typeof VectorSortFieldSchema>;
 
 /**
  * Parameters for getting all namespace statistics with optional pagination
  */
-export interface VectorGetAllStatsParams extends ListParams<VectorSortField> {
+export const VectorGetAllStatsParamsSchema = ListParamsSchema(VectorSortFieldSchema).extend({
 	/**
 	 * Filter namespaces by name substring
 	 */
-	name?: string;
-}
+	name: z.string().optional().describe('Filter namespaces by name substring'),
+});
+
+export type VectorGetAllStatsParams = z.infer<typeof VectorGetAllStatsParamsSchema>;
 
 /**
  * Paginated response for vector namespace statistics
  */
-export interface VectorStatsPaginated {
+export const VectorStatsPaginatedSchema = z.object({
 	/**
 	 * Map of namespace names to their statistics
 	 */
-	namespaces: Record<string, VectorNamespaceStats>;
+	namespaces: z
+		.record(z.string(), VectorNamespaceStatsSchema)
+		.describe('Map of namespace names to their statistics'),
 	/**
 	 * Total number of namespaces across all pages
 	 */
-	total: number;
+	total: z.number().describe('Total number of namespaces across all pages'),
 	/**
 	 * Number of namespaces requested per page
 	 */
-	limit: number;
+	limit: z.number().describe('Number of namespaces requested per page'),
 	/**
 	 * Number of namespaces skipped
 	 */
-	offset: number;
+	offset: z.number().describe('Number of namespaces skipped'),
 	/**
 	 * Whether there are more namespaces available
 	 */
-	hasMore: boolean;
-}
+	hasMore: z.boolean().describe('Whether there are more namespaces available'),
+});
+
+export type VectorStatsPaginated = z.infer<typeof VectorStatsPaginatedSchema>;
 
 /**
  * Vector storage service for managing vector embeddings and semantic search
@@ -721,7 +844,7 @@ export class VectorStorageService implements VectorStorage {
 			}
 		}
 
-		const url = buildUrl(this.#baseUrl, `/vector/2025-03-17/${encodeURIComponent(name)}`);
+		const url = buildUrl(this.#baseUrl, `/vector/${encodeURIComponent(name)}`);
 		const signal = AbortSignal.timeout(30_000);
 
 		// Transform documents to handle TTL: null → 0 for "no expiration"
@@ -780,7 +903,7 @@ export class VectorStorageService implements VectorStorage {
 
 		const url = buildUrl(
 			this.#baseUrl,
-			`/vector/2025-03-17/${encodeURIComponent(name)}/${encodeURIComponent(key)}`
+			`/vector/${encodeURIComponent(name)}/${encodeURIComponent(key)}`
 		);
 		const signal = AbortSignal.timeout(30_000); // 30s timeout for Neon cold starts
 
@@ -881,7 +1004,7 @@ export class VectorStorageService implements VectorStorage {
 			}
 		}
 
-		const url = buildUrl(this.#baseUrl, `/vector/2025-03-17/search/${encodeURIComponent(name)}`);
+		const url = buildUrl(this.#baseUrl, `/vector/search/${encodeURIComponent(name)}`);
 		const signal = AbortSignal.timeout(30_000);
 
 		const attributes: Record<string, string> = {
@@ -946,10 +1069,10 @@ export class VectorStorageService implements VectorStorage {
 		if (keys.length === 1 && firstKey) {
 			url = buildUrl(
 				this.#baseUrl,
-				`/vector/2025-03-17/${encodeURIComponent(name)}/${encodeURIComponent(firstKey)}`
+				`/vector/${encodeURIComponent(name)}/${encodeURIComponent(firstKey)}`
 			);
 		} else {
-			url = buildUrl(this.#baseUrl, `/vector/2025-03-17/${encodeURIComponent(name)}`);
+			url = buildUrl(this.#baseUrl, `/vector/${encodeURIComponent(name)}`);
 			body = safeStringify({ keys });
 		}
 
@@ -998,7 +1121,7 @@ export class VectorStorageService implements VectorStorage {
 			throw new VectorStorageNameRequiredError();
 		}
 
-		const url = buildUrl(this.#baseUrl, `/vector/2025-03-17/stats/${encodeURIComponent(name)}`);
+		const url = buildUrl(this.#baseUrl, `/vector/stats/${encodeURIComponent(name)}`);
 		const signal = AbortSignal.timeout(30_000); // 30s timeout for Neon cold starts
 
 		const res = await this.#adapter.invoke<VectorStatsResponse>(url, {
@@ -1043,10 +1166,7 @@ export class VectorStorageService implements VectorStorage {
 			queryParams.set('name', params.name);
 		}
 		const queryString = queryParams.toString();
-		const url = buildUrl(
-			this.#baseUrl,
-			`/vector/2025-03-17/stats${queryString ? `?${queryString}` : ''}`
-		);
+		const url = buildUrl(this.#baseUrl, `/vector/stats${queryString ? `?${queryString}` : ''}`);
 		const signal = AbortSignal.timeout(30_000); // 30s timeout for Neon cold starts
 
 		const res = await this.#adapter.invoke<
@@ -1068,7 +1188,7 @@ export class VectorStorageService implements VectorStorage {
 	}
 
 	async getNamespaces(): Promise<string[]> {
-		const url = buildUrl(this.#baseUrl, '/vector/2025-03-17/namespaces');
+		const url = buildUrl(this.#baseUrl, '/vector/namespaces');
 		const signal = AbortSignal.timeout(30_000); // 30s timeout for Neon cold starts
 		const res = await this.#adapter.invoke<string[]>(url, {
 			method: 'GET',
@@ -1089,7 +1209,7 @@ export class VectorStorageService implements VectorStorage {
 			throw new VectorStorageNameRequiredError();
 		}
 
-		const url = buildUrl(this.#baseUrl, `/vector/2025-03-17/${encodeURIComponent(name)}`);
+		const url = buildUrl(this.#baseUrl, `/vector/${encodeURIComponent(name)}`);
 		const signal = AbortSignal.timeout(30_000);
 
 		const res = await this.#adapter.invoke<VectorDeleteNamespaceResponse>(url, {