@namzu/sdk 30.2.0 → 31.0.0

package/src/rag/embedding.ts

@@ -1,4 +1,43 @@
-import type { EmbeddingProvider, HttpEmbeddingConfig } from '../types/rag/index.js'
+import type {
+	EmbeddingProvider,
+	HttpEmbeddingConfig,
+	RAGOperationOptions,
+} from '../types/rag/index.js'
+
+/** Each HTTP embedding batch owns a finite transport lifetime by default. */
+export const DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS = 30_000
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+
+function resolveRequestTimeoutMs(value: number | undefined): number {
+	const resolved = value ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS
+	if (!Number.isInteger(resolved) || resolved < 0 || resolved > MAX_TIMER_DELAY_MS) {
+		throw new RangeError(
+			`requestTimeoutMs must be an integer from 0 to ${MAX_TIMER_DELAY_MS}; received ${String(resolved)}`,
+		)
+	}
+	return resolved
+}
+
+function resolveBatchSize(value: number | undefined): number {
+	const resolved = value ?? 64
+	if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+		throw new RangeError(`batchSize must be a positive safe integer; received ${String(resolved)}`)
+	}
+	return resolved
+}
+
+function resolveDimensions(value: number | undefined): number {
+	const resolved = value ?? 1536
+	if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+		throw new RangeError(`dimensions must be a positive safe integer; received ${String(resolved)}`)
+	}
+	return resolved
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null
+}
 
 /**
  * Embeddings over the common HTTP shape: `POST {baseUrl}/embeddings` with
@@ -29,36 +68,94 @@ export class HttpEmbeddingProvider implements EmbeddingProvider {
 	private readonly apiKey: string
 	private readonly baseUrl: string
 	private readonly batchSize: number
+	private readonly requestTimeoutMs: number
 
 	constructor(config: HttpEmbeddingConfig) {
 		this.model = config.model
-		this.dimensions = config.dimensions ?? 1536
+		this.dimensions = resolveDimensions(config.dimensions)
 		this.apiKey = config.apiKey
 		this.baseUrl = stripTrailingSlashes(config.baseUrl)
-		this.batchSize = config.batchSize ?? 64
+		this.batchSize = resolveBatchSize(config.batchSize)
+		this.requestTimeoutMs = resolveRequestTimeoutMs(config.requestTimeoutMs)
 	}
 
-	async embed(texts: string[]): Promise<number[][]> {
+	async embed(texts: string[], options: RAGOperationOptions = {}): Promise<number[][]> {
+		options.signal?.throwIfAborted()
 		const results: number[][] = []
 
 		for (let i = 0; i < texts.length; i += this.batchSize) {
 			const batch = texts.slice(i, i + this.batchSize)
-			const batchResults = await this.callEmbeddingApi(batch)
+			const batchResults = await this.callEmbeddingApi(batch, options.signal)
 			results.push(...batchResults)
 		}
 
 		return results
 	}
 
-	async embedQuery(query: string): Promise<number[]> {
-		const [result] = await this.embed([query])
+	async embedQuery(query: string, options: RAGOperationOptions = {}): Promise<number[]> {
+		const [result] = await this.embed([query], options)
 		if (!result) {
 			throw new Error('Embedding returned no results')
 		}
 		return result
 	}
 
-	private async callEmbeddingApi(texts: string[]): Promise<number[][]> {
+	private async callEmbeddingApi(texts: string[], callerSignal?: AbortSignal): Promise<number[][]> {
+		callerSignal?.throwIfAborted()
+
+		// The provider owns this controller. A caller cancellation flows into it,
+		// while the provider's deadline never aborts the caller's controller.
+		const transport = new AbortController()
+		let rejectCallerAbort: ((reason?: unknown) => void) | undefined
+		const callerAbort = callerSignal
+			? new Promise<never>((_resolve, reject) => {
+					rejectCallerAbort = reject
+				})
+			: undefined
+		const onCallerAbort = (): void => {
+			const reason = callerSignal?.reason
+			// Settle the public operation with the caller's exact reason before
+			// aborting fetch: transports commonly turn every abort into a generic
+			// DOMException, which would erase who stopped the run.
+			rejectCallerAbort?.(reason)
+			if (!transport.signal.aborted) transport.abort(reason)
+		}
+		callerSignal?.addEventListener('abort', onCallerAbort, { once: true })
+
+		let timer: ReturnType<typeof setTimeout> | undefined
+		const timeout =
+			this.requestTimeoutMs > 0
+				? new Promise<never>((_resolve, reject) => {
+						timer = setTimeout(() => {
+							const error = new Error(
+								`Embedding request timed out after ${this.requestTimeoutMs}ms`,
+							)
+							error.name = 'TimeoutError'
+							reject(error)
+							if (!transport.signal.aborted) transport.abort(error)
+						}, this.requestTimeoutMs)
+					})
+				: undefined
+
+		const request = this.performEmbeddingRequest(texts, transport.signal)
+		// A custom or polyfilled fetch may ignore AbortSignal and reject later.
+		// Once the operation has settled, that late rejection is not allowed to
+		// become an unhandled process error.
+		request.catch(() => {})
+
+		try {
+			return await Promise.race([
+				request,
+				...(callerAbort ? [callerAbort] : []),
+				...(timeout ? [timeout] : []),
+			])
+		} finally {
+			if (timer !== undefined) clearTimeout(timer)
+			callerSignal?.removeEventListener('abort', onCallerAbort)
+		}
+	}
+
+	private async performEmbeddingRequest(texts: string[], signal: AbortSignal): Promise<number[][]> {
 		const response = await fetch(`${this.baseUrl}/embeddings`, {
 			method: 'POST',
 			headers: {
@@ -70,6 +167,7 @@ export class HttpEmbeddingProvider implements EmbeddingProvider {
 				input: texts,
 				dimensions: this.dimensions,
 			}),
+			signal,
 		})
 
 		if (!response.ok) {
@@ -77,18 +175,48 @@ export class HttpEmbeddingProvider implements EmbeddingProvider {
 			throw new Error(`Embedding API error (${response.status}): ${errorText}`)
 		}
 
-		const data = (await response.json()) as EmbeddingApiResponse
-		return data.data.sort((a, b) => a.index - b.index).map((d) => d.embedding)
+		return this.validateEmbeddingResponse(await response.json(), texts.length)
 	}
-}
 
-interface EmbeddingApiResponse {
-	data: Array<{
-		index: number
-		embedding: number[]
-	}>
-	usage: {
-		prompt_tokens: number
-		total_tokens: number
+	private validateEmbeddingResponse(value: unknown, expectedCount: number): number[][] {
+		if (!isRecord(value) || !Array.isArray(value.data)) {
+			throw new Error('Embedding API response must contain a data array')
+		}
+		if (value.data.length !== expectedCount) {
+			throw new Error(
+				`Embedding API returned ${value.data.length} vectors for ${expectedCount} inputs`,
+			)
+		}
+
+		const embeddings = new Array<number[]>(expectedCount)
+		const seen = new Set<number>()
+		for (const item of value.data) {
+			if (!isRecord(item) || !Number.isSafeInteger(item.index)) {
+				throw new Error('Embedding API response contains a non-integer index')
+			}
+			const index = item.index as number
+			if (index < 0 || index >= expectedCount) {
+				throw new Error(`Embedding API response index ${index} is outside the input range`)
+			}
+			if (seen.has(index)) {
+				throw new Error(`Embedding API response contains duplicate index ${index}`)
+			}
+			if (
+				!Array.isArray(item.embedding) ||
+				item.embedding.length !== this.dimensions ||
+				!item.embedding.every(
+					(coordinate) => typeof coordinate === 'number' && Number.isFinite(coordinate),
+				)
+			) {
+				throw new Error(
+					`Embedding API response index ${index} must contain ${this.dimensions} finite numbers`,
+				)
+			}
+
+			seen.add(index)
+			embeddings[index] = item.embedding
+		}
+
+		return embeddings
 	}
 }

package/src/rag/index.ts

@@ -28,7 +28,7 @@ export type {
 
 export { TextChunker, DEFAULT_CHUNKING_CONFIG } from './chunking.js'
 
-export { HttpEmbeddingProvider } from './embedding.js'
+export { DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS, HttpEmbeddingProvider } from './embedding.js'
 
 export { InMemoryVectorStore, cosineSimilarity } from './vector-store.js'
 

package/src/rag/ingestion.ts

@@ -6,11 +6,13 @@ import type {
 	EmbeddingProvider,
 	IngestionPipeline,
 	IngestionResult,
+	RAGOperationOptions,
 	TenantScope,
 	VectorStore,
 } from '../types/rag/index.js'
 import { generateChunkId, generateDocumentId } from '../utils/id.js'
 import { DEFAULT_CHUNKING_CONFIG, TextChunker } from './chunking.js'
+import { awaitRAGOperation } from './operation.js'
 
 export class DefaultIngestionPipeline implements IngestionPipeline {
 	private readonly chunker: TextChunker
@@ -30,7 +32,9 @@ export class DefaultIngestionPipeline implements IngestionPipeline {
 		metadata: DocumentMetadata,
 		scope: TenantScope,
 		knowledgeBaseId: KnowledgeBaseId,
+		options?: RAGOperationOptions,
 	): Promise<IngestionResult> {
+		options?.signal?.throwIfAborted()
 		const startTime = Date.now()
 		const documentId = generateDocumentId()
 
@@ -40,7 +44,14 @@ export class DefaultIngestionPipeline implements IngestionPipeline {
 		}
 
 		const texts = chunkContents.map((c) => c.content)
-		const embeddings = await this.embeddingProvider.embed(texts)
+		const embeddings = options
+			? await this.embeddingProvider.embed(texts, options)
+			: await this.embeddingProvider.embed(texts)
+		// A custom provider may accept the signal yet settle successfully after
+		// cancellation. Its cooperation is outside the kernel's control; whether
+		// Namzu now persists those late results is not. Recheck before the first
+		// state-changing store call.
+		options?.signal?.throwIfAborted()
 
 		const now = Date.now()
 		const chunks: Chunk[] = chunkContents.map((cc, i) => ({
@@ -57,7 +68,10 @@ export class DefaultIngestionPipeline implements IngestionPipeline {
 			createdAt: now,
 		}))
 
-		await this.vectorStore.upsert(chunks)
+		const upsert = options
+			? this.vectorStore.upsert(chunks, options)
+			: this.vectorStore.upsert(chunks)
+		await awaitRAGOperation(upsert, options?.signal)
 
 		const totalTokens = chunks.reduce((sum, c) => sum + c.tokenCount, 0)
 		return {

package/src/rag/knowledge-base.ts

@@ -6,6 +6,7 @@ import type {
 	IngestionResult,
 	KnowledgeBase,
 	KnowledgeBaseConfig,
+	RAGOperationOptions,
 	RetrievalConfig,
 	RetrievalQuery,
 	RetrievalResult,
@@ -54,16 +55,24 @@ export class DefaultKnowledgeBase implements KnowledgeBase {
 		this.retriever = new DefaultRetriever(vectorStore, embeddingProvider, retrievalConfig)
 	}
 
-	async ingest(content: string, metadata: DocumentMetadata = {}): Promise<IngestionResult> {
-		return this.ingestion.ingest(content, metadata, this.scope, this.id)
+	async ingest(
+		content: string,
+		metadata: DocumentMetadata = {},
+		options?: RAGOperationOptions,
+	): Promise<IngestionResult> {
+		return options
+			? this.ingestion.ingest(content, metadata, this.scope, this.id, options)
+			: this.ingestion.ingest(content, metadata, this.scope, this.id)
 	}
 
 	async remove(documentId: DocumentId): Promise<void> {
 		return this.ingestion.remove(documentId)
 	}
 
-	async query(query: RetrievalQuery): Promise<RetrievalResult> {
-		return this.retriever.retrieve(query, this.scope, this.id)
+	async query(query: RetrievalQuery, options?: RAGOperationOptions): Promise<RetrievalResult> {
+		return options
+			? this.retriever.retrieve(query, this.scope, this.id, options)
+			: this.retriever.retrieve(query, this.scope, this.id)
 	}
 
 	async clear(): Promise<void> {

package/src/rag/operation.ts

@@ -0,0 +1,28 @@
+/**
+ * Bound a host-supplied RAG promise to operation cancellation.
+ *
+ * The signal is also passed to cooperative providers. This race is the
+ * kernel-owned half of the contract: a custom store that ignores its signal
+ * may continue its own work, but it cannot keep the public operation pending
+ * or make a late result advance the caller's pipeline.
+ */
+export async function awaitRAGOperation<T>(
+	operation: Promise<T>,
+	signal?: AbortSignal,
+): Promise<T> {
+	if (!signal) return operation
+	signal.throwIfAborted()
+
+	let rejectAbort: ((reason?: unknown) => void) | undefined
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectAbort = reject
+	})
+	const onAbort = (): void => rejectAbort?.(signal.reason)
+	signal.addEventListener('abort', onAbort, { once: true })
+
+	try {
+		return await Promise.race([operation, aborted])
+	} finally {
+		signal.removeEventListener('abort', onAbort)
+	}
+}

package/src/rag/rag-tool.ts

@@ -22,7 +22,7 @@ export function createRAGTool(config: RAGToolConfig) {
 		destructive: false,
 		concurrencySafe: true,
 
-		async execute(input) {
+		async execute(input, toolContext) {
 			const kbId =
 				(input.knowledge_base_id === undefined
 					? undefined
@@ -39,10 +39,13 @@ export function createRAGTool(config: RAGToolConfig) {
 				}
 			}
 
-			const result = await kb.query({
+			const query = {
 				text: input.query,
 				config: { topK: input.top_k ?? config.topK ?? 5 },
-			})
+			}
+			const result = toolContext.abortSignal
+				? await kb.query(query, { signal: toolContext.abortSignal })
+				: await kb.query(query)
 
 			if (result.chunks.length === 0) {
 				return {

package/src/rag/retriever.ts

@@ -2,6 +2,7 @@ import { DEFAULT_RETRIEVAL_CONFIG } from '../constants/rag/index.js'
 import type { KnowledgeBaseId } from '../types/ids/index.js'
 import type {
 	EmbeddingProvider,
+	RAGOperationOptions,
 	RetrievalConfig,
 	RetrievalQuery,
 	RetrievalResult,
@@ -10,6 +11,7 @@ import type {
 	VectorSearchResult,
 	VectorStore,
 } from '../types/rag/index.js'
+import { awaitRAGOperation } from './operation.js'
 
 export { DEFAULT_RETRIEVAL_CONFIG }
 
@@ -24,7 +26,9 @@ export class DefaultRetriever implements Retriever {
 		query: RetrievalQuery,
 		scope: TenantScope,
 		knowledgeBaseId?: KnowledgeBaseId,
+		options?: RAGOperationOptions,
 	): Promise<RetrievalResult> {
+		options?.signal?.throwIfAborted()
 		const startTime = Date.now()
 		const effectiveConfig = { ...this.config, ...query.config }
 		const expandedQuery = this.expandQuery(query)
@@ -33,13 +37,31 @@ export class DefaultRetriever implements Retriever {
 
 		switch (effectiveConfig.mode) {
 			case 'vector':
-				chunks = await this.vectorSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
+				chunks = await this.vectorSearch(
+					expandedQuery,
+					scope,
+					knowledgeBaseId,
+					effectiveConfig,
+					options,
+				)
 				break
 			case 'keyword':
-				chunks = await this.keywordSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
+				chunks = await this.keywordSearch(
+					expandedQuery,
+					scope,
+					knowledgeBaseId,
+					effectiveConfig,
+					options,
+				)
 				break
 			case 'hybrid':
-				chunks = await this.hybridSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
+				chunks = await this.hybridSearch(
+					expandedQuery,
+					scope,
+					knowledgeBaseId,
+					effectiveConfig,
+					options,
+				)
 				break
 			default: {
 				const _exhaustive: never = effectiveConfig.mode
@@ -70,16 +92,24 @@ export class DefaultRetriever implements Retriever {
 		scope: TenantScope,
 		knowledgeBaseId: KnowledgeBaseId | undefined,
 		config: RetrievalConfig,
+		options?: RAGOperationOptions,
 	): Promise<VectorSearchResult[]> {
-		const embedding = await this.embeddingProvider.embedQuery(query)
-		return this.vectorStore.search({
+		const embedding = options
+			? await this.embeddingProvider.embedQuery(query, options)
+			: await this.embeddingProvider.embedQuery(query)
+		options?.signal?.throwIfAborted()
+		const storeQuery = {
 			embedding,
 			topK: config.topK,
 			tenantId: scope.tenantId,
 			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			knowledgeBaseId,
 			minScore: config.minScore,
-		})
+		}
+		const search = options
+			? this.vectorStore.search(storeQuery, options)
+			: this.vectorStore.search(storeQuery)
+		return awaitRAGOperation(search, options?.signal)
 	}
 
 	private async keywordSearch(
@@ -87,16 +117,24 @@ export class DefaultRetriever implements Retriever {
 		scope: TenantScope,
 		knowledgeBaseId: KnowledgeBaseId | undefined,
 		config: RetrievalConfig,
+		options?: RAGOperationOptions,
 	): Promise<VectorSearchResult[]> {
-		const embedding = await this.embeddingProvider.embedQuery(query)
-		const vectorResults = await this.vectorStore.search({
+		const embedding = options
+			? await this.embeddingProvider.embedQuery(query, options)
+			: await this.embeddingProvider.embedQuery(query)
+		options?.signal?.throwIfAborted()
+		const storeQuery = {
 			embedding,
 			topK: config.topK * 2,
 			tenantId: scope.tenantId,
 			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			knowledgeBaseId,
 			minScore: 0,
-		})
+		}
+		const search = options
+			? this.vectorStore.search(storeQuery, options)
+			: this.vectorStore.search(storeQuery)
+		const vectorResults = await awaitRAGOperation(search, options?.signal)
 
 		const queryTerms = this.tokenize(query)
 
@@ -123,12 +161,25 @@ export class DefaultRetriever implements Retriever {
 		scope: TenantScope,
 		knowledgeBaseId: KnowledgeBaseId | undefined,
 		config: RetrievalConfig,
+		options?: RAGOperationOptions,
 	): Promise<VectorSearchResult[]> {
 		const alpha = config.hybridAlpha ?? 0.7
 
 		const [vectorResults, keywordResults] = await Promise.all([
-			this.vectorSearch(query, scope, knowledgeBaseId, { ...config, topK: config.topK * 2 }),
-			this.keywordSearch(query, scope, knowledgeBaseId, { ...config, topK: config.topK * 2 }),
+			this.vectorSearch(
+				query,
+				scope,
+				knowledgeBaseId,
+				{ ...config, topK: config.topK * 2 },
+				options,
+			),
+			this.keywordSearch(
+				query,
+				scope,
+				knowledgeBaseId,
+				{ ...config, topK: config.topK * 2 },
+				options,
+			),
 		])
 
 		const scoreMap = new Map<string, { chunk: VectorSearchResult['chunk']; score: number }>()

package/src/rag/vector-store.ts

@@ -1,6 +1,7 @@
 import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
 import type {
 	Chunk,
+	RAGOperationOptions,
 	VectorSearchResult,
 	VectorStore,
 	VectorStoreQuery,
@@ -9,13 +10,18 @@ import type {
 export class InMemoryVectorStore implements VectorStore {
 	private chunks: Map<ChunkId, Chunk> = new Map()
 
-	async upsert(chunks: Chunk[]): Promise<void> {
+	async upsert(chunks: Chunk[], options?: RAGOperationOptions): Promise<void> {
+		options?.signal?.throwIfAborted()
 		for (const chunk of chunks) {
 			this.chunks.set(chunk.id, chunk)
 		}
 	}
 
-	async search(query: VectorStoreQuery): Promise<VectorSearchResult[]> {
+	async search(
+		query: VectorStoreQuery,
+		options?: RAGOperationOptions,
+	): Promise<VectorSearchResult[]> {
+		options?.signal?.throwIfAborted()
 		const candidates: VectorSearchResult[] = []
 
 		for (const chunk of this.chunks.values()) {