@namzu/sdk 0.4.2 → 0.4.4

package/src/rag/chunking.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `TextChunker.chunk(content, config)` dispatches by
+ *     `config.strategy`. Unknown strategy hits an exhaustive-check
+ *     throw (unreachable via types).
+ *   - `fixed` strategy: slides a window of `chunkSize` by
+ *     `chunkSize − chunkOverlap` (min 1) and emits trimmed non-empty
+ *     slices. Indices are 0-based and contiguous.
+ *   - `sentence` / `paragraph` strategies split by their separator
+ *     sets and then merge small parts until the budget fills.
+ *   - `recursive` strategy: short content returns as a single chunk;
+ *     otherwise it splits by the first separator that produces >1
+ *     parts, merges, and recurses into parts that still exceed
+ *     `chunkSize`. Falls back to `fixed` when no separator splits.
+ *   - Overlap is applied in `mergeSmallParts` via
+ *     `current.slice(current.length - chunkOverlap) + part`.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ChunkingConfig } from '../types/rag/index.js'
+
+import { TextChunker } from './chunking.js'
+
+const chunker = new TextChunker()
+
+describe('TextChunker — fixed', () => {
+	const fixed: ChunkingConfig = { strategy: 'fixed', chunkSize: 10, chunkOverlap: 2 }
+
+	it('emits trimmed non-empty slices with contiguous indices', () => {
+		const result = chunker.chunk('0123456789abcdefghij', fixed)
+		expect(result).toHaveLength(3)
+		expect(result.map((c) => c.index)).toEqual([0, 1, 2])
+	})
+
+	it('skips whitespace-only slices', () => {
+		const result = chunker.chunk('abc           def', {
+			strategy: 'fixed',
+			chunkSize: 5,
+			chunkOverlap: 0,
+		})
+		expect(result.map((c) => c.content)).not.toContain('')
+	})
+
+	it('clamps step to at least 1 when overlap >= chunkSize', () => {
+		const result = chunker.chunk('abcdefghij', {
+			strategy: 'fixed',
+			chunkSize: 3,
+			chunkOverlap: 3,
+		})
+		// step = max(1, 3-3) = 1; eagerly emits many overlapping slices
+		expect(result.length).toBeGreaterThan(1)
+	})
+})
+
+describe('TextChunker — sentence', () => {
+	it('splits by sentence separators and merges up to the budget', () => {
+		const result = chunker.chunk('First sentence. Second sentence. Third sentence.', {
+			strategy: 'sentence',
+			chunkSize: 100,
+			chunkOverlap: 0,
+		})
+		expect(result.length).toBeGreaterThanOrEqual(1)
+		expect(result[0]?.content).toContain('First sentence')
+	})
+})
+
+describe('TextChunker — paragraph', () => {
+	it('splits by paragraph separators', () => {
+		const result = chunker.chunk('para one\n\npara two\n\npara three', {
+			strategy: 'paragraph',
+			chunkSize: 200,
+			chunkOverlap: 0,
+		})
+		expect(result.length).toBeGreaterThanOrEqual(1)
+	})
+})
+
+describe('TextChunker — recursive', () => {
+	it('short content fits into a single chunk', () => {
+		const result = chunker.chunk('tiny', {
+			strategy: 'recursive',
+			chunkSize: 100,
+			chunkOverlap: 0,
+		})
+		expect(result).toEqual([{ content: 'tiny', index: 0 }])
+	})
+
+	it('long content recursively splits to stay within chunkSize', () => {
+		const content = 'paragraph one. more text.\n\nparagraph two. more.'
+		const result = chunker.chunk(content, {
+			strategy: 'recursive',
+			chunkSize: 30,
+			chunkOverlap: 0,
+		})
+		for (const c of result) {
+			expect(c.content.length).toBeLessThanOrEqual(30)
+		}
+	})
+
+	it('empty or whitespace-only content yields empty result', () => {
+		expect(chunker.chunk('   ', { strategy: 'recursive', chunkSize: 10, chunkOverlap: 0 })).toEqual(
+			[],
+		)
+	})
+})

package/src/rag/context-assembler.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `assembleRAGContext([], cfg)` returns `{content: '', sources: [],
+ *     tokenCount: 0}` immediately.
+ *   - Token estimation: `Math.ceil(text.length / 4)`.
+ *   - `headerTemplate` is prepended before any chunks.
+ *   - Chunks are included in order while their accumulated token count
+ *     stays below `maxTokens`; the first chunk that would overflow is
+ *     dropped along with every subsequent chunk (early break).
+ *   - `includeMetadata: true` prefixes each chunk with a bracketed
+ *     metadata line (`Source: …`, `Title: …`, `Relevance: XX.X%`).
+ *   - `sources[]` captures a truncated preview (first 200 chars) of
+ *     each INCLUDED chunk; skipped chunks are NOT present.
+ *   - `content` is the joined parts with `config.separator`;
+ *     `tokenCount` is re-estimated from the joined content.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { VectorSearchResult } from '../types/rag/index.js'
+
+import { assembleRAGContext } from './context-assembler.js'
+
+function result(
+	content: string,
+	score = 0.9,
+	meta: Record<string, unknown> = {},
+): VectorSearchResult {
+	return {
+		chunk: {
+			id: `c_${content.slice(0, 3)}` as ChunkId,
+			documentId: 'doc_1' as DocumentId,
+			knowledgeBaseId: 'kb_1' as KnowledgeBaseId,
+			tenantId: 't_1' as TenantId,
+			content,
+			index: 0,
+			tokenCount: 0,
+			metadata: meta,
+			createdAt: 0,
+		},
+		score,
+	}
+}
+
+describe('assembleRAGContext', () => {
+	it('returns empty for empty input', () => {
+		expect(assembleRAGContext([])).toEqual({ content: '', sources: [], tokenCount: 0 })
+	})
+
+	it('joins non-empty chunks with the configured separator', () => {
+		const ctx = assembleRAGContext([result('alpha'), result('beta')], {
+			separator: ' | ',
+			maxTokens: 1000,
+			includeMetadata: false,
+			headerTemplate: undefined,
+		})
+		expect(ctx.content).toBe('alpha | beta')
+	})
+
+	it('includes a headerTemplate before chunks when provided', () => {
+		const ctx = assembleRAGContext([result('body')], {
+			separator: '\n',
+			maxTokens: 1000,
+			includeMetadata: false,
+			headerTemplate: '### Knowledge',
+		})
+		expect(ctx.content.startsWith('### Knowledge\n')).toBe(true)
+	})
+
+	it('early-breaks once a chunk would overflow maxTokens (and drops subsequent)', () => {
+		const long = 'a'.repeat(200) // ~50 tokens per the /4 estimate
+		const ctx = assembleRAGContext([result('tiny'), result(long), result('also-tiny')], {
+			separator: '\n',
+			maxTokens: 20,
+			includeMetadata: false,
+			headerTemplate: undefined,
+		})
+		expect(ctx.content).toBe('tiny')
+		// third chunk was NOT included even though it would fit — the loop breaks on first overflow.
+		expect(ctx.sources.map((s) => s.chunk.slice(0, 10))).toEqual(['tiny'])
+	})
+
+	it('includeMetadata prefixes entries with bracketed metadata', () => {
+		const ctx = assembleRAGContext([result('body', 0.7567, { source: 'repo', title: 'README' })], {
+			separator: '\n',
+			maxTokens: 1000,
+			includeMetadata: true,
+		})
+		expect(ctx.content).toContain('[Source: repo | Title: README | Relevance: 75.7%]')
+	})
+
+	it('sources[] carries the first 200 chars of each included chunk', () => {
+		const long = 'x'.repeat(500)
+		const ctx = assembleRAGContext([result(long)], {
+			separator: '\n',
+			maxTokens: 10000,
+			includeMetadata: false,
+		})
+		expect(ctx.sources[0]?.chunk).toHaveLength(200)
+	})
+
+	it('tokenCount is derived from the final joined content', () => {
+		const ctx = assembleRAGContext([result('abcd'), result('efgh')], {
+			separator: '',
+			maxTokens: 1000,
+			includeMetadata: false,
+			headerTemplate: undefined,
+		})
+		// 'abcdefgh' → Math.ceil(8 / 4) = 2
+		expect(ctx.tokenCount).toBe(2)
+	})
+})

package/src/rag/embedding.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `OpenRouterEmbeddingProvider`:
+ *     - Defaults: dimensions = 1536; baseUrl = openrouter.ai/api/v1;
+ *       batchSize = 64.
+ *     - `embed(texts)` batches into `batchSize` slices and concatenates
+ *       results in input order.
+ *     - Each HTTP call posts `{model, input, dimensions}` to
+ *       `${baseUrl}/embeddings` with the Bearer authorization header.
+ *     - The API response is sorted by `index` ascending before extracting
+ *       `.embedding`, so results match input order even if the server
+ *       re-orders.
+ *     - `embedQuery(query)` returns the first result from `embed([query])`;
+ *       throws when the response is empty.
+ *     - `!response.ok` → throws with `Embedding API error (<status>): <body>`.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { OpenRouterEmbeddingProvider } from './embedding.js'
+
+describe('OpenRouterEmbeddingProvider', () => {
+	let fetchMock: ReturnType<typeof vi.fn>
+
+	beforeEach(() => {
+		fetchMock = vi.fn()
+		global.fetch = fetchMock as unknown as typeof fetch
+	})
+
+	afterEach(() => {
+		vi.restoreAllMocks()
+	})
+
+	it('carries model / dimensions defaults + batchSize', () => {
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		expect(p.model).toBe('m')
+		expect(p.dimensions).toBe(1536)
+	})
+
+	it('honors overrides for dimensions + baseUrl + batchSize', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({ data: [{ index: 0, embedding: [1, 2, 3] }] }),
+		})
+		const p = new OpenRouterEmbeddingProvider({
+			apiKey: 'k',
+			model: 'm',
+			dimensions: 256,
+			baseUrl: 'https://custom.example/api',
+		})
+		await p.embed(['x'])
+
+		expect(fetchMock).toHaveBeenCalledWith(
+			'https://custom.example/api/embeddings',
+			expect.objectContaining({
+				method: 'POST',
+				headers: expect.objectContaining({
+					Authorization: 'Bearer k',
+					'Content-Type': 'application/json',
+				}),
+			}),
+		)
+		const body = JSON.parse((fetchMock.mock.calls[0]?.[1] as { body: string }).body)
+		expect(body).toEqual({ model: 'm', input: ['x'], dimensions: 256 })
+		expect(p.dimensions).toBe(256)
+	})
+
+	it('batches into batchSize slices', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({
+				data: [
+					{ index: 0, embedding: [1] },
+					{ index: 1, embedding: [2] },
+				],
+			}),
+		})
+		const p = new OpenRouterEmbeddingProvider({
+			apiKey: 'k',
+			model: 'm',
+			batchSize: 2,
+		})
+		await p.embed(['a', 'b', 'c', 'd'])
+		expect(fetchMock).toHaveBeenCalledTimes(2)
+	})
+
+	it('sorts response by index before extracting embeddings', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({
+				data: [
+					{ index: 2, embedding: [3] },
+					{ index: 0, embedding: [1] },
+					{ index: 1, embedding: [2] },
+				],
+			}),
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		expect(await p.embed(['a', 'b', 'c'])).toEqual([[1], [2], [3]])
+	})
+
+	it('embedQuery returns the first result', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({ data: [{ index: 0, embedding: [9, 9] }] }),
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		expect(await p.embedQuery('hi')).toEqual([9, 9])
+	})
+
+	it('embedQuery throws when the response is empty', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({ data: [] }),
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		await expect(p.embedQuery('hi')).rejects.toThrow(/no results/)
+	})
+
+	it('throws on non-OK HTTP response', async () => {
+		fetchMock.mockResolvedValue({
+			ok: false,
+			status: 503,
+			text: async () => 'service unavailable',
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		await expect(p.embed(['hi'])).rejects.toThrow(/503.*service unavailable/)
+	})
+})

package/src/rag/ingestion.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `DefaultIngestionPipeline.ingest(content, metadata, scope, kbId)`:
+ *     - Generates a fresh `documentId` per call.
+ *     - Chunks via `TextChunker.chunk(content, chunkingConfig)`.
+ *     - Returns zero-chunk result when the chunker emits nothing.
+ *     - Calls `embeddingProvider.embed([...chunkTexts])` exactly once
+ *       with every chunk in order.
+ *     - Each resulting `Chunk` carries:
+ *       - a fresh `id`,
+ *       - the generated `documentId`,
+ *       - the passed `knowledgeBaseId`,
+ *       - `scope.tenantId`,
+ *       - the original `chunkContent` + `chunkIndex` metadata,
+ *       - `tokenCount = Math.ceil(content.length / 4)`.
+ *     - Calls `vectorStore.upsert(chunks)` exactly once.
+ *     - Totals `tokenCount` across chunks and reports `durationMs`.
+ *   - `remove(documentId)` delegates to `vectorStore.deleteByDocument`.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+import type { DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { Chunk, EmbeddingProvider, TenantScope, VectorStore } from '../types/rag/index.js'
+
+import { DefaultIngestionPipeline } from './ingestion.js'
+
+const KB = 'kb_1' as KnowledgeBaseId
+const TENANT = 't_1' as TenantId
+const scope: TenantScope = { tenantId: TENANT }
+
+function makeVectorStore(): VectorStore {
+	return {
+		upsert: vi.fn<(chunks: Chunk[]) => Promise<void>>(),
+		search: vi.fn(),
+		delete: vi.fn(),
+		deleteByDocument: vi.fn(),
+		deleteByKnowledgeBase: vi.fn(),
+	} as unknown as VectorStore
+}
+
+function makeEmbedder(): EmbeddingProvider {
+	return {
+		id: 'mock',
+		model: 'x',
+		dimensions: 3,
+		embed: vi.fn(async (texts: string[]) => texts.map(() => [1, 0, 0])),
+		embedQuery: vi.fn(async () => [1, 0, 0]),
+	}
+}
+
+describe('DefaultIngestionPipeline — ingest', () => {
+	it('returns zero-chunk result when the chunker emits nothing', async () => {
+		const vs = makeVectorStore()
+		const emb = makeEmbedder()
+		// chunkSize 10, no content at all → chunker returns []
+		const pipeline = new DefaultIngestionPipeline(vs, emb, {
+			strategy: 'fixed',
+			chunkSize: 10,
+			chunkOverlap: 0,
+		})
+		const result = await pipeline.ingest('   ', {}, scope, KB)
+		expect(result.chunkCount).toBe(0)
+		expect(result.totalTokens).toBe(0)
+		expect(vs.upsert).not.toHaveBeenCalled()
+	})
+
+	it('chunks content, embeds every chunk once, upserts once', async () => {
+		const vs = makeVectorStore()
+		const emb = makeEmbedder()
+		const pipeline = new DefaultIngestionPipeline(vs, emb, {
+			strategy: 'fixed',
+			chunkSize: 10,
+			chunkOverlap: 0,
+		})
+
+		const result = await pipeline.ingest('a'.repeat(25), { source: 'repo' }, scope, KB)
+
+		expect(emb.embed).toHaveBeenCalledTimes(1)
+		expect(vs.upsert).toHaveBeenCalledTimes(1)
+		expect(result.chunkCount).toBeGreaterThan(1)
+
+		const upsertedChunks = vi.mocked(vs.upsert).mock.calls[0]?.[0] ?? []
+		for (const c of upsertedChunks) {
+			expect(c.documentId).toBe(result.documentId)
+			expect(c.knowledgeBaseId).toBe(KB)
+			expect(c.tenantId).toBe(TENANT)
+			expect(c.metadata.source).toBe('repo')
+			expect(c.metadata.chunkIndex).toBeDefined()
+			expect(c.tokenCount).toBe(Math.ceil(c.content.length / 4))
+		}
+	})
+
+	it('generates a fresh documentId per ingest call', async () => {
+		const pipeline = new DefaultIngestionPipeline(makeVectorStore(), makeEmbedder())
+		const a = await pipeline.ingest('alpha', {}, scope, KB)
+		const b = await pipeline.ingest('beta', {}, scope, KB)
+		expect(a.documentId).not.toBe(b.documentId)
+	})
+})
+
+describe('DefaultIngestionPipeline — remove', () => {
+	it('delegates to vectorStore.deleteByDocument', async () => {
+		const vs = makeVectorStore()
+		const pipeline = new DefaultIngestionPipeline(vs, makeEmbedder())
+		await pipeline.remove('doc_9' as DocumentId)
+		expect(vs.deleteByDocument).toHaveBeenCalledWith('doc_9')
+	})
+})
+
+// Avoid the unused zod import — used in type coverage indirectly.
+void z

package/src/rag/knowledge-base.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `DefaultKnowledgeBase` is a composition layer: it builds an
+ *     ingestion pipeline + a retriever from its config and delegates
+ *     `ingest` / `query` / `remove` / `clear` to them.
+ *   - `id` is set from `config.id` if provided, else generated once
+ *     via `generateKnowledgeBaseId` — never regenerated later.
+ *   - `ingest(content, metadata)` invokes the ingestion pipeline with
+ *     the configured scope + kb id; returns whatever the pipeline
+ *     returns.
+ *   - `query(query)` invokes the retriever with scope + kb id.
+ *   - `clear()` calls `vectorStore.deleteByKnowledgeBase(id, tenantId)`.
+ *   - `remove(documentId)` calls `vectorStore.deleteByDocument`.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { EmbeddingProvider, VectorStore } from '../types/rag/index.js'
+
+import { DefaultKnowledgeBase } from './knowledge-base.js'
+
+const TENANT = 't_1' as TenantId
+
+function makeVectorStore(): VectorStore {
+	return {
+		upsert: vi.fn(),
+		search: vi.fn(async () => []),
+		delete: vi.fn(),
+		deleteByDocument: vi.fn(),
+		deleteByKnowledgeBase: vi.fn(),
+	}
+}
+
+function makeEmbedder(): EmbeddingProvider {
+	return {
+		id: 'mock',
+		model: 'x',
+		dimensions: 3,
+		embed: vi.fn(async (texts: string[]) => texts.map(() => [1, 0, 0])),
+		embedQuery: vi.fn(async () => [1, 0, 0]),
+	}
+}
+
+describe('DefaultKnowledgeBase', () => {
+	it('uses the id provided in config when set', () => {
+		const kb = new DefaultKnowledgeBase(
+			{ id: 'kb_fixed' as KnowledgeBaseId, name: 'kb', tenantId: TENANT },
+			makeVectorStore(),
+			makeEmbedder(),
+		)
+		expect(kb.id).toBe('kb_fixed')
+		expect(kb.config.id).toBe('kb_fixed')
+	})
+
+	it('generates an id when none is provided', () => {
+		const kb = new DefaultKnowledgeBase(
+			{ name: 'kb', tenantId: TENANT },
+			makeVectorStore(),
+			makeEmbedder(),
+		)
+		expect(kb.id).toMatch(/^kb_/)
+	})
+
+	it('ingest delegates to the ingestion pipeline and carries metadata through', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase(
+			{ id: 'kb_fixed' as KnowledgeBaseId, name: 'kb', tenantId: TENANT },
+			vs,
+			makeEmbedder(),
+		)
+		const result = await kb.ingest('hello world', { source: 'readme' })
+		expect(result.documentId).toMatch(/^doc_/)
+		expect(vs.upsert).toHaveBeenCalled()
+		const chunks = vi.mocked(vs.upsert).mock.calls[0]?.[0] ?? []
+		expect(chunks[0]?.knowledgeBaseId).toBe('kb_fixed')
+		expect(chunks[0]?.tenantId).toBe(TENANT)
+	})
+
+	it('remove delegates to vectorStore.deleteByDocument', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase({ name: 'kb', tenantId: TENANT }, vs, makeEmbedder())
+		await kb.remove('doc_1' as DocumentId)
+		expect(vs.deleteByDocument).toHaveBeenCalledWith('doc_1')
+	})
+
+	it('clear delegates to vectorStore.deleteByKnowledgeBase with id + tenantId', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase(
+			{ id: 'kb_fixed' as KnowledgeBaseId, name: 'kb', tenantId: TENANT },
+			vs,
+			makeEmbedder(),
+		)
+		await kb.clear()
+		expect(vs.deleteByKnowledgeBase).toHaveBeenCalledWith('kb_fixed', TENANT)
+	})
+
+	it('query delegates to retriever', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase({ name: 'kb', tenantId: TENANT }, vs, makeEmbedder())
+		const out = await kb.query({ text: 'hi' })
+		expect(out.mode).toBeDefined()
+		expect(vs.search).toHaveBeenCalled()
+	})
+})