@namzu/sdk 0.1.1 → 0.1.3

package/src/rag/retriever.ts

@@ -1,184 +1,177 @@
+import { DEFAULT_RETRIEVAL_CONFIG } from '../constants/rag/index.js'
 import type { KnowledgeBaseId } from '../types/ids/index.js'
 import type {
-  EmbeddingProvider,
-  RetrievalConfig,
-  RetrievalMode,
-  RetrievalQuery,
-  RetrievalResult,
-  Retriever,
-  TenantScope,
-  VectorSearchResult,
-  VectorStore,
+	EmbeddingProvider,
+	RetrievalConfig,
+	RetrievalQuery,
+	RetrievalResult,
+	Retriever,
+	TenantScope,
+	VectorSearchResult,
+	VectorStore,
 } from '../types/rag/index.js'
 
-export const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig = {
-  mode: 'vector',
-  topK: 5,
-  minScore: 0.3,
-  hybridAlpha: 0.7,
-}
+export { DEFAULT_RETRIEVAL_CONFIG }
 
 export class DefaultRetriever implements Retriever {
-  constructor(
-    private readonly vectorStore: VectorStore,
-    private readonly embeddingProvider: EmbeddingProvider,
-    private readonly config: RetrievalConfig = DEFAULT_RETRIEVAL_CONFIG,
-  ) {}
-
-  async retrieve(
-    query: RetrievalQuery,
-    scope: TenantScope,
-    knowledgeBaseId?: KnowledgeBaseId,
-  ): Promise<RetrievalResult> {
-    const startTime = Date.now()
-    const effectiveConfig = { ...this.config, ...query.config }
-    const expandedQuery = this.expandQuery(query)
-
-    let chunks: VectorSearchResult[]
-
-    switch (effectiveConfig.mode) {
-      case 'vector':
-        chunks = await this.vectorSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
-        break
-      case 'keyword':
-        chunks = await this.keywordSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
-        break
-      case 'hybrid':
-        chunks = await this.hybridSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
-        break
-      default: {
-        const _exhaustive: never = effectiveConfig.mode
-        throw new Error(`Unhandled retrieval mode: ${_exhaustive}`)
-      }
-    }
-
-    return {
-      chunks,
-      query: query.text,
-      expandedQuery: expandedQuery !== query.text ? expandedQuery : undefined,
-      mode: effectiveConfig.mode,
-      durationMs: Date.now() - startTime,
-    }
-  }
-
-  private expandQuery(query: RetrievalQuery): string {
-    if (!query.threadMessages || query.threadMessages.length === 0) {
-      return query.text
-    }
-
-    const recentContext = query.threadMessages.slice(-3).join(' ')
-    return `${query.text}\n\nContext: ${recentContext}`
-  }
-
-  private async vectorSearch(
-    query: string,
-    scope: TenantScope,
-    knowledgeBaseId: KnowledgeBaseId | undefined,
-    config: RetrievalConfig,
-  ): Promise<VectorSearchResult[]> {
-    const embedding = await this.embeddingProvider.embedQuery(query)
-    return this.vectorStore.search({
-      embedding,
-      topK: config.topK,
-      tenantId: scope.tenantId,
-      knowledgeBaseId,
-      minScore: config.minScore,
-    })
-  }
-
-  private async keywordSearch(
-    query: string,
-    scope: TenantScope,
-    knowledgeBaseId: KnowledgeBaseId | undefined,
-    config: RetrievalConfig,
-  ): Promise<VectorSearchResult[]> {
-    const embedding = await this.embeddingProvider.embedQuery(query)
-    const vectorResults = await this.vectorStore.search({
-      embedding,
-      topK: config.topK * 2,
-      tenantId: scope.tenantId,
-      knowledgeBaseId,
-      minScore: 0,
-    })
-
-    const queryTerms = this.tokenize(query)
-    return vectorResults
-      .map(result => ({
-        ...result,
-        score: this.bm25Score(queryTerms, this.tokenize(result.chunk.content)),
-      }))
-      .filter(r => r.score > 0)
-      .sort((a, b) => b.score - a.score)
-      .slice(0, config.topK)
-  }
-
-  private async hybridSearch(
-    query: string,
-    scope: TenantScope,
-    knowledgeBaseId: KnowledgeBaseId | undefined,
-    config: RetrievalConfig,
-  ): 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 }),
-    ])
-
-    const scoreMap = new Map<string, { chunk: VectorSearchResult['chunk']; score: number }>()
-
-    for (const result of vectorResults) {
-      scoreMap.set(result.chunk.id, {
-        chunk: result.chunk,
-        score: alpha * result.score,
-      })
-    }
-
-    for (const result of keywordResults) {
-      const existing = scoreMap.get(result.chunk.id)
-      if (existing) {
-        existing.score += (1 - alpha) * result.score
-      } else {
-        scoreMap.set(result.chunk.id, {
-          chunk: result.chunk,
-          score: (1 - alpha) * result.score,
-        })
-      }
-    }
-
-    return [...scoreMap.values()]
-      .sort((a, b) => b.score - a.score)
-      .slice(0, config.topK)
-  }
-
-  private tokenize(text: string): string[] {
-    return text
-      .toLowerCase()
-      .replace(/[^\w\s]/g, ' ')
-      .split(/\s+/)
-      .filter(t => t.length > 1)
-  }
-
-  private bm25Score(queryTerms: string[], docTerms: string[]): number {
-    const k1 = 1.2
-    const b = 0.75
-    const avgDl = 256
-    const dl = docTerms.length
-
-    const termFreq = new Map<string, number>()
-    for (const term of docTerms) {
-      termFreq.set(term, (termFreq.get(term) ?? 0) + 1)
-    }
-
-    let score = 0
-    for (const term of queryTerms) {
-      const tf = termFreq.get(term) ?? 0
-      if (tf === 0) continue
-      const numerator = tf * (k1 + 1)
-      const denominator = tf + k1 * (1 - b + b * (dl / avgDl))
-      score += numerator / denominator
-    }
-
-    return score
-  }
+	constructor(
+		private readonly vectorStore: VectorStore,
+		private readonly embeddingProvider: EmbeddingProvider,
+		private readonly config: RetrievalConfig = DEFAULT_RETRIEVAL_CONFIG,
+	) {}
+
+	async retrieve(
+		query: RetrievalQuery,
+		scope: TenantScope,
+		knowledgeBaseId?: KnowledgeBaseId,
+	): Promise<RetrievalResult> {
+		const startTime = Date.now()
+		const effectiveConfig = { ...this.config, ...query.config }
+		const expandedQuery = this.expandQuery(query)
+
+		let chunks: VectorSearchResult[]
+
+		switch (effectiveConfig.mode) {
+			case 'vector':
+				chunks = await this.vectorSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
+				break
+			case 'keyword':
+				chunks = await this.keywordSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
+				break
+			case 'hybrid':
+				chunks = await this.hybridSearch(expandedQuery, scope, knowledgeBaseId, effectiveConfig)
+				break
+			default: {
+				const _exhaustive: never = effectiveConfig.mode
+				throw new Error(`Unhandled retrieval mode: ${_exhaustive}`)
+			}
+		}
+
+		return {
+			chunks,
+			query: query.text,
+			expandedQuery: expandedQuery !== query.text ? expandedQuery : undefined,
+			mode: effectiveConfig.mode,
+			durationMs: Date.now() - startTime,
+		}
+	}
+
+	private expandQuery(query: RetrievalQuery): string {
+		if (!query.threadMessages || query.threadMessages.length === 0) {
+			return query.text
+		}
+
+		const recentContext = query.threadMessages.slice(-3).join(' ')
+		return `${query.text}\n\nContext: ${recentContext}`
+	}
+
+	private async vectorSearch(
+		query: string,
+		scope: TenantScope,
+		knowledgeBaseId: KnowledgeBaseId | undefined,
+		config: RetrievalConfig,
+	): Promise<VectorSearchResult[]> {
+		const embedding = await this.embeddingProvider.embedQuery(query)
+		return this.vectorStore.search({
+			embedding,
+			topK: config.topK,
+			tenantId: scope.tenantId,
+			knowledgeBaseId,
+			minScore: config.minScore,
+		})
+	}
+
+	private async keywordSearch(
+		query: string,
+		scope: TenantScope,
+		knowledgeBaseId: KnowledgeBaseId | undefined,
+		config: RetrievalConfig,
+	): Promise<VectorSearchResult[]> {
+		const embedding = await this.embeddingProvider.embedQuery(query)
+		const vectorResults = await this.vectorStore.search({
+			embedding,
+			topK: config.topK * 2,
+			tenantId: scope.tenantId,
+			knowledgeBaseId,
+			minScore: 0,
+		})
+
+		const queryTerms = this.tokenize(query)
+		return vectorResults
+			.map((result) => ({
+				...result,
+				score: this.bm25Score(queryTerms, this.tokenize(result.chunk.content)),
+			}))
+			.filter((r) => r.score > 0)
+			.sort((a, b) => b.score - a.score)
+			.slice(0, config.topK)
+	}
+
+	private async hybridSearch(
+		query: string,
+		scope: TenantScope,
+		knowledgeBaseId: KnowledgeBaseId | undefined,
+		config: RetrievalConfig,
+	): 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 }),
+		])
+
+		const scoreMap = new Map<string, { chunk: VectorSearchResult['chunk']; score: number }>()
+
+		for (const result of vectorResults) {
+			scoreMap.set(result.chunk.id, {
+				chunk: result.chunk,
+				score: alpha * result.score,
+			})
+		}
+
+		for (const result of keywordResults) {
+			const existing = scoreMap.get(result.chunk.id)
+			if (existing) {
+				existing.score += (1 - alpha) * result.score
+			} else {
+				scoreMap.set(result.chunk.id, {
+					chunk: result.chunk,
+					score: (1 - alpha) * result.score,
+				})
+			}
+		}
+
+		return [...scoreMap.values()].sort((a, b) => b.score - a.score).slice(0, config.topK)
+	}
+
+	private tokenize(text: string): string[] {
+		return text
+			.toLowerCase()
+			.replace(/[^\w\s]/g, ' ')
+			.split(/\s+/)
+			.filter((t) => t.length > 1)
+	}
+
+	private bm25Score(queryTerms: string[], docTerms: string[]): number {
+		const k1 = 1.2
+		const b = 0.75
+		const avgDl = 256
+		const dl = docTerms.length
+
+		const termFreq = new Map<string, number>()
+		for (const term of docTerms) {
+			termFreq.set(term, (termFreq.get(term) ?? 0) + 1)
+		}
+
+		let score = 0
+		for (const term of queryTerms) {
+			const tf = termFreq.get(term) ?? 0
+			if (tf === 0) continue
+			const numerator = tf * (k1 + 1)
+			const denominator = tf + k1 * (1 - b + b * (dl / avgDl))
+			score += numerator / denominator
+		}
+
+		return score
+	}
 }

package/src/rag/vector-store.ts

@@ -1,84 +1,87 @@
 import type { ChunkId, DocumentId, KnowledgeBaseId } from '../types/ids/index.js'
 import type {
-  Chunk,
-  VectorStore,
-  VectorStoreQuery,
-  VectorSearchResult,
+	Chunk,
+	VectorSearchResult,
+	VectorStore,
+	VectorStoreQuery,
 } from '../types/rag/index.js'
 
 export class InMemoryVectorStore implements VectorStore {
-  private chunks: Map<ChunkId, Chunk> = new Map()
+	private chunks: Map<ChunkId, Chunk> = new Map()
 
-  async upsert(chunks: Chunk[]): Promise<void> {
-    for (const chunk of chunks) {
-      this.chunks.set(chunk.id, chunk)
-    }
-  }
+	async upsert(chunks: Chunk[]): Promise<void> {
+		for (const chunk of chunks) {
+			this.chunks.set(chunk.id, chunk)
+		}
+	}
 
-  async search(query: VectorStoreQuery): Promise<VectorSearchResult[]> {
-    const candidates: VectorSearchResult[] = []
+	async search(query: VectorStoreQuery): Promise<VectorSearchResult[]> {
+		const candidates: VectorSearchResult[] = []
 
-    for (const chunk of this.chunks.values()) {
-      if (chunk.tenantId !== query.tenantId) continue
-      if (query.knowledgeBaseId && chunk.knowledgeBaseId !== query.knowledgeBaseId) continue
-      if (!chunk.embedding) continue
+		for (const chunk of this.chunks.values()) {
+			if (chunk.tenantId !== query.tenantId) continue
+			if (query.knowledgeBaseId && chunk.knowledgeBaseId !== query.knowledgeBaseId) continue
+			if (!chunk.embedding) continue
 
-      if (query.filter) {
-        let matches = true
-        for (const [key, value] of Object.entries(query.filter)) {
-          if (chunk.metadata[key] !== value) {
-            matches = false
-            break
-          }
-        }
-        if (!matches) continue
-      }
+			if (query.filter) {
+				let matches = true
+				for (const [key, value] of Object.entries(query.filter)) {
+					if (chunk.metadata[key] !== value) {
+						matches = false
+						break
+					}
+				}
+				if (!matches) continue
+			}
 
-      const score = cosineSimilarity(query.embedding, chunk.embedding)
-      if (query.minScore !== undefined && score < query.minScore) continue
-      candidates.push({ chunk, score })
-    }
+			const score = cosineSimilarity(query.embedding, chunk.embedding)
+			if (query.minScore !== undefined && score < query.minScore) continue
+			candidates.push({ chunk, score })
+		}
 
-    candidates.sort((a, b) => b.score - a.score)
-    return candidates.slice(0, query.topK)
-  }
+		candidates.sort((a, b) => b.score - a.score)
+		return candidates.slice(0, query.topK)
+	}
 
-  async delete(chunkIds: ChunkId[]): Promise<void> {
-    for (const id of chunkIds) {
-      this.chunks.delete(id)
-    }
-  }
+	async delete(chunkIds: ChunkId[]): Promise<void> {
+		for (const id of chunkIds) {
+			this.chunks.delete(id)
+		}
+	}
 
-  async deleteByDocument(documentId: DocumentId): Promise<void> {
-    for (const [id, chunk] of this.chunks) {
-      if (chunk.documentId === documentId) {
-        this.chunks.delete(id)
-      }
-    }
-  }
+	async deleteByDocument(documentId: DocumentId): Promise<void> {
+		for (const [id, chunk] of this.chunks) {
+			if (chunk.documentId === documentId) {
+				this.chunks.delete(id)
+			}
+		}
+	}
 
-  async deleteByKnowledgeBase(knowledgeBaseId: KnowledgeBaseId, tenantId: string): Promise<void> {
-    for (const [id, chunk] of this.chunks) {
-      if (chunk.knowledgeBaseId === knowledgeBaseId && chunk.tenantId === tenantId) {
-        this.chunks.delete(id)
-      }
-    }
-  }
+	async deleteByKnowledgeBase(knowledgeBaseId: KnowledgeBaseId, tenantId: string): Promise<void> {
+		for (const [id, chunk] of this.chunks) {
+			if (chunk.knowledgeBaseId === knowledgeBaseId && chunk.tenantId === tenantId) {
+				this.chunks.delete(id)
+			}
+		}
+	}
 }
 
 export function cosineSimilarity(a: number[], b: number[]): number {
-  if (a.length !== b.length) return 0
+	if (a.length !== b.length) return 0
 
-  let dotProduct = 0
-  let normA = 0
-  let normB = 0
+	let dotProduct = 0
+	let normA = 0
+	let normB = 0
 
-  for (let i = 0; i < a.length; i++) {
-    dotProduct += a[i]! * b[i]!
-    normA += a[i]! * a[i]!
-    normB += b[i]! * b[i]!
-  }
+	for (let i = 0; i < a.length; i++) {
+		const ai = a[i]
+		const bi = b[i]
+		if (ai === undefined || bi === undefined) break
+		dotProduct += ai * bi
+		normA += ai * ai
+		normB += bi * bi
+	}
 
-  const denominator = Math.sqrt(normA) * Math.sqrt(normB)
-  return denominator === 0 ? 0 : dotProduct / denominator
+	const denominator = Math.sqrt(normA) * Math.sqrt(normB)
+	return denominator === 0 ? 0 : dotProduct / denominator
 }

package/src/registry/ManagedRegistry.ts

@@ -1,56 +1,67 @@
-import { type Logger, getRootLogger } from "../utils/logger.js";
-import { Registry } from "./Registry.js";
+import { type Logger, getRootLogger } from '../utils/logger.js'
+import { Registry } from './Registry.js'
 
 export interface ManagedRegistryConfig<TDefinition> {
-	componentName: string;
-	idField?: keyof TDefinition & string;
-	logger?: Logger;
+	componentName: string
+	idField?: keyof TDefinition & string
+	logger?: Logger
 }
 
 export class ManagedRegistry<TDefinition> extends Registry<TDefinition> {
-	protected log: Logger;
-	private idField?: keyof TDefinition & string;
+	protected log: Logger
+	private idField?: keyof TDefinition & string
 
 	constructor(config: ManagedRegistryConfig<TDefinition>) {
-		super();
-		this.idField = config.idField;
+		super()
+		this.idField = config.idField
 		this.log = (config.logger ?? getRootLogger()).child({
 			component: config.componentName,
-		});
+		})
 	}
 
-	override register(id: string, item: TDefinition): void;
-	register(item: TDefinition): void;
-	register(items: TDefinition[]): void;
-	register(
-		idOrItem: string | TDefinition | TDefinition[],
-		maybeItem?: TDefinition,
-	): void {
+	override register(id: string, item: TDefinition): void
+	override register(item: TDefinition): void
+	override register(items: TDefinition[]): void
+	override register(idOrItem: string | TDefinition | TDefinition[], maybeItem?: TDefinition): void {
 		if (Array.isArray(idOrItem)) {
 			for (const item of idOrItem) {
-				this.register(item);
+				this.register(item)
 			}
-			return;
+			return
 		}
 
-		const item = typeof idOrItem === "string" ? maybeItem! : idOrItem;
-		const id =
-			typeof idOrItem === "string" ? idOrItem : String(item[this.idField!]);
+		if (typeof idOrItem === 'string') {
+			if (!maybeItem) {
+				throw new Error('register(id, item) requires an item argument')
+			}
+			const id = idOrItem
+			const item = maybeItem
+			if (this.has(id)) {
+				this.log.warn(`"${id}" already registered, overwriting.`)
+			}
+			super.register(id, item)
+			this.log.info(`Registered: ${id}`)
+			return
+		}
+
+		const item = idOrItem
+		if (!this.idField) {
+			throw new Error('register(item) requires idField to be configured')
+		}
+		const id = String(item[this.idField])
 
 		if (this.has(id)) {
-			this.log.warn(`"${id}" already registered, overwriting.`);
+			this.log.warn(`"${id}" already registered, overwriting.`)
 		}
-		super.register(id, item);
-		this.log.info(`Registered: ${id}`);
+		super.register(id, item)
+		this.log.info(`Registered: ${id}`)
 	}
 
 	getOrThrow(id: string): TDefinition {
-		const item = this.get(id);
+		const item = this.get(id)
 		if (!item) {
-			throw new Error(
-				`Not found: "${id}". Available: ${this.listIds().join(", ")}`,
-			);
+			throw new Error(`Not found: "${id}". Available: ${this.listIds().join(', ')}`)
 		}
-		return item;
+		return item
 	}
 }

package/src/registry/Registry.ts

@@ -1,35 +1,35 @@
 export class Registry<TDefinition> {
-  protected items: Map<string, TDefinition> = new Map()
+	protected items: Map<string, TDefinition> = new Map()
 
-  register(id: string, item: TDefinition): void {
-    this.items.set(id, item)
-  }
+	register(id: string, item: TDefinition): void {
+		this.items.set(id, item)
+	}
 
-  get(id: string): TDefinition | undefined {
-    return this.items.get(id)
-  }
+	get(id: string): TDefinition | undefined {
+		return this.items.get(id)
+	}
 
-  has(id: string): boolean {
-    return this.items.has(id)
-  }
+	has(id: string): boolean {
+		return this.items.has(id)
+	}
 
-  getAll(): TDefinition[] {
-    return Array.from(this.items.values())
-  }
+	getAll(): TDefinition[] {
+		return Array.from(this.items.values())
+	}
 
-  listIds(): string[] {
-    return Array.from(this.items.keys())
-  }
+	listIds(): string[] {
+		return Array.from(this.items.keys())
+	}
 
-  unregister(id: string): boolean {
-    return this.items.delete(id)
-  }
+	unregister(id: string): boolean {
+		return this.items.delete(id)
+	}
 
-  clear(): void {
-    this.items.clear()
-  }
+	clear(): void {
+		this.items.clear()
+	}
 
-  size(): number {
-    return this.items.size
-  }
+	size(): number {
+		return this.items.size
+	}
 }