@namzu/sdk 0.1.1

package/src/rag/retriever.ts

@@ -0,0 +1,184 @@
+import type { KnowledgeBaseId } from '../types/ids/index.js'
+import type {
+  EmbeddingProvider,
+  RetrievalConfig,
+  RetrievalMode,
+  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 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
+  }
+}

package/src/rag/vector-store.ts

@@ -0,0 +1,84 @@
+import type { ChunkId, DocumentId, KnowledgeBaseId } from '../types/ids/index.js'
+import type {
+  Chunk,
+  VectorStore,
+  VectorStoreQuery,
+  VectorSearchResult,
+} from '../types/rag/index.js'
+
+export class InMemoryVectorStore implements VectorStore {
+  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 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
+
+      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 })
+    }
+
+    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 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)
+      }
+    }
+  }
+}
+
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) return 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]!
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB)
+  return denominator === 0 ? 0 : dotProduct / denominator
+}

package/src/registry/ManagedRegistry.ts

@@ -0,0 +1,56 @@
+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;
+}
+
+export class ManagedRegistry<TDefinition> extends Registry<TDefinition> {
+	protected log: Logger;
+	private idField?: keyof TDefinition & string;
+
+	constructor(config: ManagedRegistryConfig<TDefinition>) {
+		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 {
+		if (Array.isArray(idOrItem)) {
+			for (const item of idOrItem) {
+				this.register(item);
+			}
+			return;
+		}
+
+		const item = typeof idOrItem === "string" ? maybeItem! : idOrItem;
+		const id =
+			typeof idOrItem === "string" ? idOrItem : String(item[this.idField!]);
+
+		if (this.has(id)) {
+			this.log.warn(`"${id}" already registered, overwriting.`);
+		}
+		super.register(id, item);
+		this.log.info(`Registered: ${id}`);
+	}
+
+	getOrThrow(id: string): TDefinition {
+		const item = this.get(id);
+		if (!item) {
+			throw new Error(
+				`Not found: "${id}". Available: ${this.listIds().join(", ")}`,
+			);
+		}
+		return item;
+	}
+}

package/src/registry/Registry.ts

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

package/src/registry/agent/definitions.ts

@@ -0,0 +1,74 @@
+import type { AgentDefinition, AgentType } from "../../types/agent/index.js";
+import type {
+	Agent,
+	BaseAgentConfig,
+	BaseAgentResult,
+} from "../../types/agent/index.js";
+import { type Logger, getRootLogger } from "../../utils/logger.js";
+import { Registry } from "../Registry.js";
+
+export class AgentRegistry extends Registry<AgentDefinition> {
+	private log: Logger;
+
+	constructor() {
+		super();
+		this.log = getRootLogger().child({ component: "AgentRegistry" });
+	}
+
+	override register(id: string, definition: AgentDefinition): void;
+	register(definition: AgentDefinition): void;
+	register(definitions: AgentDefinition[]): void;
+	register(
+		idOrDef: string | AgentDefinition | AgentDefinition[],
+		maybeDef?: AgentDefinition,
+	): void {
+		if (Array.isArray(idOrDef)) {
+			for (const def of idOrDef) {
+				this.register(def);
+			}
+			return;
+		}
+
+		const def = typeof idOrDef === "string" ? maybeDef! : idOrDef;
+		const id = typeof idOrDef === "string" ? idOrDef : def.info.id;
+
+		if (this.has(id)) {
+			this.log.warn(`Agent "${id}" already registered, overwriting.`);
+		}
+		super.register(id, def);
+		this.log.info(`Agent registered: ${id}`);
+	}
+
+	getOrThrow(id: string): AgentDefinition {
+		const def = this.get(id);
+		if (!def) {
+			throw new Error(
+				`Agent not found: "${id}". Available: ${this.listIds().join(", ")}`,
+			);
+		}
+		return def;
+	}
+
+	resolve(agentId: string): Agent<BaseAgentConfig, BaseAgentResult> {
+		return this.getOrThrow(agentId).typedAgent;
+	}
+
+	listByType(type: AgentType): AgentDefinition[] {
+		return this.getAll().filter((d) => d.typedAgent.type === type);
+	}
+
+	search(query: { category?: string; query?: string }): AgentDefinition[] {
+		return this.getAll().filter((def) => {
+			if (query.category && def.info.category !== query.category) return false;
+			if (query.query) {
+				const q = query.query.toLowerCase();
+				if (
+					!def.info.name.toLowerCase().includes(q) &&
+					!def.info.description.toLowerCase().includes(q)
+				)
+					return false;
+			}
+			return true;
+		});
+	}
+}

package/src/registry/agent/index.ts

@@ -0,0 +1 @@
+export { AgentRegistry } from "./definitions.js";

package/src/registry/connector/definitions.ts

@@ -0,0 +1,52 @@
+import type { ConnectorDefinition } from "../../types/connector/index.js";
+import { type Logger, getRootLogger } from "../../utils/logger.js";
+import { Registry } from "../Registry.js";
+
+export class ConnectorRegistry extends Registry<ConnectorDefinition> {
+	private log: Logger;
+
+	constructor() {
+		super();
+		this.log = getRootLogger().child({ component: "ConnectorRegistry" });
+	}
+
+	override register(id: string, definition: ConnectorDefinition): void;
+	register(definition: ConnectorDefinition): void;
+	register(definitions: ConnectorDefinition[]): void;
+	register(
+		idOrDef: string | ConnectorDefinition | ConnectorDefinition[],
+		maybeDef?: ConnectorDefinition,
+	): void {
+		if (Array.isArray(idOrDef)) {
+			for (const def of idOrDef) {
+				this.register(def);
+			}
+			return;
+		}
+
+		const def = typeof idOrDef === "string" ? maybeDef! : idOrDef;
+		const id = typeof idOrDef === "string" ? idOrDef : def.id;
+
+		if (this.has(id)) {
+			this.log.warn(`Connector "${id}" is already registered, overwriting.`);
+		}
+		super.register(id, def);
+		this.log.info(`Connector registered: ${id}`);
+	}
+
+	getOrThrow(id: string): ConnectorDefinition {
+		const def = this.get(id);
+		if (!def) {
+			throw new Error(
+				`Connector not found: "${id}". Available: ${this.listIds().join(", ")}`,
+			);
+		}
+		return def;
+	}
+
+	listByType(
+		connectionType: ConnectorDefinition["connectionType"],
+	): ConnectorDefinition[] {
+		return this.getAll().filter((d) => d.connectionType === connectionType);
+	}
+}

package/src/registry/connector/scoped.ts

@@ -0,0 +1,129 @@
+import type {
+  ScopedConnectorConfig,
+  ResolvedConnectorConfig,
+  ConnectorConfig,
+  ConnectorScope,
+  ScopeRef,
+  ScopeChain,
+  AuthConfig,
+} from '../../types/connector/index.js'
+import { CONNECTOR_SCOPE_ORDER } from '../../types/connector/index.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+
+function scopeKey(scope: ConnectorScope, scopeId: string, connectorId: string): string {
+  return `${scope}:${scopeId}:${connectorId}`
+}
+
+export class ScopedConnectorRegistry {
+  private configs: Map<string, ScopedConnectorConfig> = new Map()
+  private log: Logger
+
+  constructor() {
+    this.log = getRootLogger().child({ component: 'ScopedConnectorRegistry' })
+  }
+
+  set(config: ScopedConnectorConfig): void {
+    const key = scopeKey(config.scope.scope, config.scope.scopeId, config.connectorId)
+    this.configs.set(key, config)
+    this.log.info(`Scoped config set: ${key}`)
+  }
+
+  remove(scope: ScopeRef, connectorId: string): boolean {
+    const key = scopeKey(scope.scope, scope.scopeId, connectorId)
+    const removed = this.configs.delete(key)
+    if (removed) {
+      this.log.info(`Scoped config removed: ${key}`)
+    }
+    return removed
+  }
+
+  getAt(scope: ScopeRef, connectorId: string): ScopedConnectorConfig | undefined {
+    return this.configs.get(scopeKey(scope.scope, scope.scopeId, connectorId))
+  }
+
+  resolve(connectorId: string, chain: ScopeChain): ResolvedConnectorConfig | undefined {
+    const layers: ScopedConnectorConfig[] = []
+
+    for (const scope of CONNECTOR_SCOPE_ORDER) {
+      const scopeId = chain[scope]
+      if (!scopeId) continue
+
+      const config = this.configs.get(scopeKey(scope, scopeId, connectorId))
+      if (config) {
+        layers.push(config)
+      }
+    }
+
+    if (layers.length === 0) return undefined
+
+    return this.mergeLayers(connectorId, layers)
+  }
+
+  listForConnector(connectorId: string): ScopedConnectorConfig[] {
+    const results: ScopedConnectorConfig[] = []
+    for (const config of this.configs.values()) {
+      if (config.connectorId === connectorId) {
+        results.push(config)
+      }
+    }
+    return results
+  }
+
+  listAtScope(scope: ScopeRef): ScopedConnectorConfig[] {
+    const prefix = `${scope.scope}:${scope.scopeId}:`
+    const results: ScopedConnectorConfig[] = []
+    for (const [key, config] of this.configs.entries()) {
+      if (key.startsWith(prefix)) {
+        results.push(config)
+      }
+    }
+    return results
+  }
+
+  private mergeLayers(
+    connectorId: string,
+    layers: ScopedConnectorConfig[],
+  ): ResolvedConnectorConfig {
+    let mergedOptions: Record<string, unknown> = {}
+    let mergedAuth: AuthConfig | undefined
+    let mergedEnabled = true
+    let mergedPartialConfig: Partial<ConnectorConfig> = {}
+    const resolvedFrom: ScopeRef[] = []
+
+    for (const layer of layers) {
+      resolvedFrom.push(layer.scope)
+
+      if (layer.options) {
+        mergedOptions = { ...mergedOptions, ...layer.options }
+      }
+
+      if (layer.auth !== undefined) {
+        mergedAuth = layer.auth
+      }
+
+      if (layer.enabled !== undefined) {
+        mergedEnabled = layer.enabled
+      }
+
+      if (layer.config) {
+        mergedPartialConfig = { ...mergedPartialConfig, ...layer.config }
+      }
+    }
+
+    const config: ConnectorConfig = {
+      connectorId,
+      name: mergedPartialConfig.name ?? connectorId,
+      auth: mergedAuth ?? mergedPartialConfig.auth,
+      options: mergedOptions,
+    }
+
+    return {
+      connectorId,
+      config,
+      auth: mergedAuth,
+      enabled: mergedEnabled,
+      options: mergedOptions,
+      resolvedFrom,
+    }
+  }
+}

package/src/registry/index.ts

@@ -0,0 +1,11 @@
+export { Registry } from './Registry.js'
+export { ManagedRegistry } from './ManagedRegistry.js'
+export type { ManagedRegistryConfig } from './ManagedRegistry.js'
+
+export { ToolRegistry } from './tool/execute.js'
+export type { ToolExecutionResult } from './tool/execute.js'
+
+export { ConnectorRegistry } from './connector/definitions.js'
+export { ScopedConnectorRegistry } from './connector/scoped.js'
+
+export { AgentRegistry } from './agent/definitions.js'