@namzu/sdk 0.1.1 → 0.1.2

package/src/rag/embedding.ts

@@ -1,72 +1,73 @@
 import type { EmbeddingProvider, OpenRouterEmbeddingConfig } from '../types/rag/index.js'
 
 export class OpenRouterEmbeddingProvider implements EmbeddingProvider {
-  readonly id = 'openrouter-embedding'
-  readonly model: string
-  readonly dimensions: number
+	readonly id = 'openrouter-embedding'
+	readonly model: string
+	readonly dimensions: number
 
-  private readonly apiKey: string
-  private readonly baseUrl: string
-  private readonly batchSize: number
+	private readonly apiKey: string
+	private readonly baseUrl: string
+	private readonly batchSize: number
 
-  constructor(config: OpenRouterEmbeddingConfig) {
-    this.model = config.model
-    this.dimensions = config.dimensions ?? 1536
-    this.apiKey = config.apiKey
-    this.baseUrl = config.baseUrl ?? 'https://openrouter.ai/api/v1'
-    this.batchSize = config.batchSize ?? 64
-  }
+	constructor(config: OpenRouterEmbeddingConfig) {
+		this.model = config.model
+		this.dimensions = config.dimensions ?? 1536
+		this.apiKey = config.apiKey
+		this.baseUrl = config.baseUrl ?? 'https://openrouter.ai/api/v1'
+		this.batchSize = config.batchSize ?? 64
+	}
 
-  async embed(texts: string[]): Promise<number[][]> {
-    const results: number[][] = []
+	async embed(texts: string[]): Promise<number[][]> {
+		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)
-      results.push(...batchResults)
-    }
+		for (let i = 0; i < texts.length; i += this.batchSize) {
+			const batch = texts.slice(i, i + this.batchSize)
+			const batchResults = await this.callEmbeddingApi(batch)
+			results.push(...batchResults)
+		}
 
-    return results
-  }
+		return results
+	}
 
-  async embedQuery(query: string): Promise<number[]> {
-    const [result] = await this.embed([query])
-    return result!
-  }
+	async embedQuery(query: string): Promise<number[]> {
+		const [result] = await this.embed([query])
+		if (!result) {
+			throw new Error('Embedding returned no results')
+		}
+		return result
+	}
 
-  private async callEmbeddingApi(texts: string[]): Promise<number[][]> {
-    const response = await fetch(`${this.baseUrl}/embeddings`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify({
-        model: this.model,
-        input: texts,
-        dimensions: this.dimensions,
-      }),
-    })
+	private async callEmbeddingApi(texts: string[]): Promise<number[][]> {
+		const response = await fetch(`${this.baseUrl}/embeddings`, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				Authorization: `Bearer ${this.apiKey}`,
+			},
+			body: JSON.stringify({
+				model: this.model,
+				input: texts,
+				dimensions: this.dimensions,
+			}),
+		})
 
-    if (!response.ok) {
-      const errorText = await response.text()
-      throw new Error(`Embedding API error (${response.status}): ${errorText}`)
-    }
+		if (!response.ok) {
+			const errorText = await response.text()
+			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)
-  }
+		const data = (await response.json()) as EmbeddingApiResponse
+		return data.data.sort((a, b) => a.index - b.index).map((d) => d.embedding)
+	}
 }
 
 interface EmbeddingApiResponse {
-  data: Array<{
-    index: number
-    embedding: number[]
-  }>
-  usage: {
-    prompt_tokens: number
-    total_tokens: number
-  }
+	data: Array<{
+		index: number
+		embedding: number[]
+	}>
+	usage: {
+		prompt_tokens: number
+		total_tokens: number
+	}
 }

package/src/rag/index.ts

@@ -1,29 +1,29 @@
 export type {
-  TenantScope,
-  DocumentMetadata,
-  Document,
-  Chunk,
-  ChunkContent,
-  ChunkingStrategy,
-  ChunkingConfig,
-  Chunker,
-  EmbeddingProvider,
-  EmbeddingConfig,
-  VectorSearchResult,
-  VectorStoreQuery,
-  VectorStore,
-  RetrievalMode,
-  RetrievalConfig,
-  RetrievalQuery,
-  RetrievalResult,
-  Retriever,
-  IngestionResult,
-  IngestionPipeline,
-  KnowledgeBaseConfig,
-  KnowledgeBase,
-  RAGToolInput,
-  RAGContextConfig,
-  RAGContext,
+	TenantScope,
+	DocumentMetadata,
+	Document,
+	Chunk,
+	ChunkContent,
+	ChunkingStrategy,
+	ChunkingConfig,
+	Chunker,
+	EmbeddingProvider,
+	EmbeddingConfig,
+	VectorSearchResult,
+	VectorStoreQuery,
+	VectorStore,
+	RetrievalMode,
+	RetrievalConfig,
+	RetrievalQuery,
+	RetrievalResult,
+	Retriever,
+	IngestionResult,
+	IngestionPipeline,
+	KnowledgeBaseConfig,
+	KnowledgeBase,
+	RAGToolInput,
+	RAGContextConfig,
+	RAGContext,
 } from '../types/rag/index.js'
 
 export { TextChunker, DEFAULT_CHUNKING_CONFIG } from './chunking.js'

package/src/rag/ingestion.ts

@@ -1,77 +1,77 @@
 import type { DocumentId, KnowledgeBaseId } from '../types/ids/index.js'
 import type {
-  Chunk,
-  ChunkingConfig,
-  DocumentMetadata,
-  EmbeddingProvider,
-  IngestionPipeline,
-  IngestionResult,
-  TenantScope,
-  VectorStore,
+	Chunk,
+	ChunkingConfig,
+	DocumentMetadata,
+	EmbeddingProvider,
+	IngestionPipeline,
+	IngestionResult,
+	TenantScope,
+	VectorStore,
 } from '../types/rag/index.js'
-import { generateDocumentId, generateChunkId } from '../utils/id.js'
-import { TextChunker, DEFAULT_CHUNKING_CONFIG } from './chunking.js'
+import { generateChunkId, generateDocumentId } from '../utils/id.js'
+import { DEFAULT_CHUNKING_CONFIG, TextChunker } from './chunking.js'
 
 export class DefaultIngestionPipeline implements IngestionPipeline {
-  private readonly chunker: TextChunker
-  private readonly chunkingConfig: ChunkingConfig
+	private readonly chunker: TextChunker
+	private readonly chunkingConfig: ChunkingConfig
 
-  constructor(
-    private readonly vectorStore: VectorStore,
-    private readonly embeddingProvider: EmbeddingProvider,
-    chunkingConfig?: Partial<ChunkingConfig>,
-  ) {
-    this.chunker = new TextChunker()
-    this.chunkingConfig = { ...DEFAULT_CHUNKING_CONFIG, ...chunkingConfig }
-  }
+	constructor(
+		private readonly vectorStore: VectorStore,
+		private readonly embeddingProvider: EmbeddingProvider,
+		chunkingConfig?: Partial<ChunkingConfig>,
+	) {
+		this.chunker = new TextChunker()
+		this.chunkingConfig = { ...DEFAULT_CHUNKING_CONFIG, ...chunkingConfig }
+	}
 
-  async ingest(
-    content: string,
-    metadata: DocumentMetadata,
-    scope: TenantScope,
-    knowledgeBaseId: KnowledgeBaseId,
-  ): Promise<IngestionResult> {
-    const startTime = Date.now()
-    const documentId = generateDocumentId()
+	async ingest(
+		content: string,
+		metadata: DocumentMetadata,
+		scope: TenantScope,
+		knowledgeBaseId: KnowledgeBaseId,
+	): Promise<IngestionResult> {
+		const startTime = Date.now()
+		const documentId = generateDocumentId()
 
-    const chunkContents = this.chunker.chunk(content, this.chunkingConfig)
-    if (chunkContents.length === 0) {
-      return { documentId, chunkCount: 0, totalTokens: 0, durationMs: Date.now() - startTime }
-    }
+		const chunkContents = this.chunker.chunk(content, this.chunkingConfig)
+		if (chunkContents.length === 0) {
+			return { documentId, chunkCount: 0, totalTokens: 0, durationMs: Date.now() - startTime }
+		}
 
-    const texts = chunkContents.map(c => c.content)
-    const embeddings = await this.embeddingProvider.embed(texts)
+		const texts = chunkContents.map((c) => c.content)
+		const embeddings = await this.embeddingProvider.embed(texts)
 
-    const now = Date.now()
-    const chunks: Chunk[] = chunkContents.map((cc, i) => ({
-      id: generateChunkId(),
-      documentId,
-      knowledgeBaseId,
-      tenantId: scope.tenantId,
-      content: cc.content,
-      index: cc.index,
-      tokenCount: estimateTokens(cc.content),
-      embedding: embeddings[i],
-      metadata: { ...metadata, chunkIndex: cc.index },
-      createdAt: now,
-    }))
+		const now = Date.now()
+		const chunks: Chunk[] = chunkContents.map((cc, i) => ({
+			id: generateChunkId(),
+			documentId,
+			knowledgeBaseId,
+			tenantId: scope.tenantId,
+			content: cc.content,
+			index: cc.index,
+			tokenCount: estimateTokens(cc.content),
+			embedding: embeddings[i],
+			metadata: { ...metadata, chunkIndex: cc.index },
+			createdAt: now,
+		}))
 
-    await this.vectorStore.upsert(chunks)
+		await this.vectorStore.upsert(chunks)
 
-    const totalTokens = chunks.reduce((sum, c) => sum + c.tokenCount, 0)
-    return {
-      documentId,
-      chunkCount: chunks.length,
-      totalTokens,
-      durationMs: Date.now() - startTime,
-    }
-  }
+		const totalTokens = chunks.reduce((sum, c) => sum + c.tokenCount, 0)
+		return {
+			documentId,
+			chunkCount: chunks.length,
+			totalTokens,
+			durationMs: Date.now() - startTime,
+		}
+	}
 
-  async remove(documentId: DocumentId): Promise<void> {
-    await this.vectorStore.deleteByDocument(documentId)
-  }
+	async remove(documentId: DocumentId): Promise<void> {
+		await this.vectorStore.deleteByDocument(documentId)
+	}
 }
 
 function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4)
+	return Math.ceil(text.length / 4)
 }

package/src/rag/knowledge-base.ts

@@ -1,72 +1,72 @@
 import type { DocumentId, KnowledgeBaseId } from '../types/ids/index.js'
 import type {
-  ChunkingConfig,
-  DocumentMetadata,
-  EmbeddingProvider,
-  IngestionResult,
-  KnowledgeBase,
-  KnowledgeBaseConfig,
-  RetrievalConfig,
-  RetrievalQuery,
-  RetrievalResult,
-  TenantScope,
-  VectorStore,
+	ChunkingConfig,
+	DocumentMetadata,
+	EmbeddingProvider,
+	IngestionResult,
+	KnowledgeBase,
+	KnowledgeBaseConfig,
+	RetrievalConfig,
+	RetrievalQuery,
+	RetrievalResult,
+	TenantScope,
+	VectorStore,
 } from '../types/rag/index.js'
 import { generateKnowledgeBaseId } from '../utils/id.js'
-import { DefaultIngestionPipeline } from './ingestion.js'
-import { DefaultRetriever, DEFAULT_RETRIEVAL_CONFIG } from './retriever.js'
 import { DEFAULT_CHUNKING_CONFIG } from './chunking.js'
+import { DefaultIngestionPipeline } from './ingestion.js'
+import { DEFAULT_RETRIEVAL_CONFIG, DefaultRetriever } from './retriever.js'
 
 export class DefaultKnowledgeBase implements KnowledgeBase {
-  readonly id: KnowledgeBaseId
-  readonly config: KnowledgeBaseConfig
+	readonly id: KnowledgeBaseId
+	readonly config: KnowledgeBaseConfig
 
-  private readonly ingestion: DefaultIngestionPipeline
-  private readonly retriever: DefaultRetriever
-  private readonly scope: TenantScope
-  private readonly vectorStore: VectorStore
+	private readonly ingestion: DefaultIngestionPipeline
+	private readonly retriever: DefaultRetriever
+	private readonly scope: TenantScope
+	private readonly vectorStore: VectorStore
 
-  constructor(
-    config: KnowledgeBaseConfig,
-    vectorStore: VectorStore,
-    embeddingProvider: EmbeddingProvider,
-  ) {
-    this.vectorStore = vectorStore
-    this.id = config.id ?? generateKnowledgeBaseId()
-    this.config = { ...config, id: this.id }
+	constructor(
+		config: KnowledgeBaseConfig,
+		vectorStore: VectorStore,
+		embeddingProvider: EmbeddingProvider,
+	) {
+		this.vectorStore = vectorStore
+		this.id = config.id ?? generateKnowledgeBaseId()
+		this.config = { ...config, id: this.id }
 
-    this.scope = {
-      tenantId: config.tenantId,
-      namespace: config.namespace,
-    }
+		this.scope = {
+			tenantId: config.tenantId,
+			namespace: config.namespace,
+		}
 
-    const chunkingConfig: ChunkingConfig = {
-      ...DEFAULT_CHUNKING_CONFIG,
-      ...config.chunking,
-    }
+		const chunkingConfig: ChunkingConfig = {
+			...DEFAULT_CHUNKING_CONFIG,
+			...config.chunking,
+		}
 
-    const retrievalConfig: RetrievalConfig = {
-      ...DEFAULT_RETRIEVAL_CONFIG,
-      ...config.retrieval,
-    }
+		const retrievalConfig: RetrievalConfig = {
+			...DEFAULT_RETRIEVAL_CONFIG,
+			...config.retrieval,
+		}
 
-    this.ingestion = new DefaultIngestionPipeline(vectorStore, embeddingProvider, chunkingConfig)
-    this.retriever = new DefaultRetriever(vectorStore, embeddingProvider, retrievalConfig)
-  }
+		this.ingestion = new DefaultIngestionPipeline(vectorStore, embeddingProvider, chunkingConfig)
+		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 = {}): Promise<IngestionResult> {
+		return this.ingestion.ingest(content, metadata, this.scope, this.id)
+	}
 
-  async remove(documentId: DocumentId): Promise<void> {
-    return this.ingestion.remove(documentId)
-  }
+	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): Promise<RetrievalResult> {
+		return this.retriever.retrieve(query, this.scope, this.id)
+	}
 
-  async clear(): Promise<void> {
-    await this.vectorStore.deleteByKnowledgeBase(this.id, this.scope.tenantId)
-  }
+	async clear(): Promise<void> {
+		await this.vectorStore.deleteByKnowledgeBase(this.id, this.scope.tenantId)
+	}
 }

package/src/rag/rag-tool.ts

@@ -5,58 +5,61 @@ import type { RAGToolConfig } from '../types/rag/index.js'
 import { assembleRAGContext } from './context-assembler.js'
 
 const ragInputSchema = z.object({
-  query: z.string().min(1).describe('The search query to find relevant knowledge'),
-  knowledge_base_id: z.string().optional().describe('ID of a specific knowledge base to search'),
-  top_k: z.number().int().min(1).max(20).optional().describe('Number of results to retrieve'),
+	query: z.string().min(1).describe('The search query to find relevant knowledge'),
+	knowledge_base_id: z.string().optional().describe('ID of a specific knowledge base to search'),
+	top_k: z.number().int().min(1).max(20).optional().describe('Number of results to retrieve'),
 })
 
 export function createRAGTool(config: RAGToolConfig) {
-  return defineTool({
-    name: 'knowledge_search',
-    description:
-      'Search the knowledge base for relevant information. Use this tool when you need to find specific facts, documentation, or context that may be stored in the knowledge base.',
-    inputSchema: ragInputSchema,
-    category: 'analysis',
-    permissions: ['network_access'],
-    readOnly: true,
-    destructive: false,
-    concurrencySafe: true,
-
-    async execute(input) {
-      const kbId = (input.knowledge_base_id as KnowledgeBaseId | undefined) ?? config.defaultKnowledgeBaseId
-      const kb = kbId ? config.knowledgeBases.get(kbId) : config.knowledgeBases.values().next().value
-
-      if (!kb) {
-        return {
-          success: false,
-          output: '',
-          error: `Knowledge base not found: ${kbId ?? 'none configured'}`,
-        }
-      }
-
-      const result = await kb.query({
-        text: input.query,
-        config: { topK: input.top_k ?? config.topK ?? 5 },
-      })
-
-      if (result.chunks.length === 0) {
-        return {
-          success: true,
-          output: 'No relevant information found in the knowledge base for this query.',
-        }
-      }
-
-      const context = assembleRAGContext(result.chunks, config.contextConfig)
-
-      return {
-        success: true,
-        output: context.content,
-        data: {
-          sources: context.sources,
-          mode: result.mode,
-          durationMs: result.durationMs,
-        },
-      }
-    },
-  })
+	return defineTool({
+		name: 'knowledge_search',
+		description:
+			'Search the knowledge base for relevant information. Use this tool when you need to find specific facts, documentation, or context that may be stored in the knowledge base.',
+		inputSchema: ragInputSchema,
+		category: 'analysis',
+		permissions: ['network_access'],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+
+		async execute(input) {
+			const kbId =
+				(input.knowledge_base_id as KnowledgeBaseId | undefined) ?? config.defaultKnowledgeBaseId
+			const kb = kbId
+				? config.knowledgeBases.get(kbId)
+				: config.knowledgeBases.values().next().value
+
+			if (!kb) {
+				return {
+					success: false,
+					output: '',
+					error: `Knowledge base not found: ${kbId ?? 'none configured'}`,
+				}
+			}
+
+			const result = await kb.query({
+				text: input.query,
+				config: { topK: input.top_k ?? config.topK ?? 5 },
+			})
+
+			if (result.chunks.length === 0) {
+				return {
+					success: true,
+					output: 'No relevant information found in the knowledge base for this query.',
+				}
+			}
+
+			const context = assembleRAGContext(result.chunks, config.contextConfig)
+
+			return {
+				success: true,
+				output: context.content,
+				data: {
+					sources: context.sources,
+					mode: result.mode,
+					durationMs: result.durationMs,
+				},
+			}
+		},
+	})
 }