@namzu/sdk 0.1.1 → 0.1.2

package/src/provider/telemetry/setup.ts

@@ -1,135 +1,125 @@
-import { NodeSDK } from '@opentelemetry/sdk-node'
-import { Resource } from '@opentelemetry/resources'
-import { SimpleSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'
+import { type Meter, type Tracer, metrics, trace } from '@opentelemetry/api'
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { Resource } from '@opentelemetry/resources'
 import {
-  MeterProvider,
-  PeriodicExportingMetricReader,
-  ConsoleMetricExporter,
+	ConsoleMetricExporter,
+	MeterProvider,
+	PeriodicExportingMetricReader,
 } from '@opentelemetry/sdk-metrics'
-import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
-import { trace, metrics, type Tracer, type Meter } from '@opentelemetry/api'
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'
 import type { TelemetryConfig } from '../../types/telemetry/index.js'
-import { getRootLogger } from '../../utils/logger.js'
 import { toErrorMessage } from '../../utils/error.js'
+import { getRootLogger } from '../../utils/logger.js'
 import { VERSION } from '../../version.js'
 
 const logger = getRootLogger().child({ component: 'TelemetryProvider' })
 
 export class TelemetryProvider {
-  private sdk: NodeSDK | null = null
-  private meterProvider: MeterProvider | null = null
-  private config: TelemetryConfig
-  private _tracer: Tracer | null = null
-  private _meter: Meter | null = null
-
-  constructor(config: TelemetryConfig) {
-    this.config = config
-  }
-
-  get tracer(): Tracer {
-    if (!this._tracer) {
-      this._tracer = trace.getTracer(
-        this.config.serviceName,
-        this.config.serviceVersion ?? VERSION,
-      )
-    }
-    return this._tracer
-  }
-
-  get meter(): Meter {
-    if (!this._meter) {
-      this._meter = metrics.getMeter(
-        this.config.serviceName,
-        this.config.serviceVersion ?? VERSION,
-      )
-    }
-    return this._meter
-  }
-
-  async start(): Promise<void> {
-    if (this.config.exporterType === 'none') {
-      logger.info('Telemetry disabled (exporterType=none)')
-      return
-    }
-
-    const resource = new Resource({
-      'service.name': this.config.serviceName,
-      'service.version': this.config.serviceVersion ?? VERSION,
-    })
-
-    const traceExporter =
-      this.config.exporterType === 'otlp'
-        ? new OTLPTraceExporter({
-            url: this.config.otlpEndpoint
-              ? `${this.config.otlpEndpoint}/v1/traces`
-              : undefined,
-            headers: this.config.otlpHeaders,
-          })
-        : new ConsoleSpanExporter()
-
-    const metricExporter =
-      this.config.exporterType === 'otlp'
-        ? new OTLPMetricExporter({
-            url: this.config.otlpEndpoint
-              ? `${this.config.otlpEndpoint}/v1/metrics`
-              : undefined,
-            headers: this.config.otlpHeaders,
-          })
-        : new ConsoleMetricExporter()
-
-    this.meterProvider = new MeterProvider({
-      resource,
-      readers: [
-        new PeriodicExportingMetricReader({
-          exporter: metricExporter,
-          exportIntervalMillis: this.config.metricExportIntervalMs ?? 10_000,
-        }),
-      ],
-    })
-    metrics.setGlobalMeterProvider(this.meterProvider)
-
-    this.sdk = new NodeSDK({
-      resource,
-      spanProcessor: new SimpleSpanProcessor(traceExporter),
-    })
-
-    this.sdk.start()
-    logger.info(`Telemetry started (exporter=${this.config.exporterType})`)
-  }
-
-  async shutdown(): Promise<void> {
-    try {
-      if (this.meterProvider) {
-        await this.meterProvider.shutdown()
-      }
-      if (this.sdk) {
-        await this.sdk.shutdown()
-      }
-      logger.info('Telemetry shutdown complete')
-    } catch (err) {
-      logger.error('Telemetry shutdown error', {
-        error: toErrorMessage(err),
-      })
-    }
-  }
+	private sdk: NodeSDK | null = null
+	private meterProvider: MeterProvider | null = null
+	private config: TelemetryConfig
+	private _tracer: Tracer | null = null
+	private _meter: Meter | null = null
+
+	constructor(config: TelemetryConfig) {
+		this.config = config
+	}
+
+	get tracer(): Tracer {
+		if (!this._tracer) {
+			this._tracer = trace.getTracer(this.config.serviceName, this.config.serviceVersion ?? VERSION)
+		}
+		return this._tracer
+	}
+
+	get meter(): Meter {
+		if (!this._meter) {
+			this._meter = metrics.getMeter(this.config.serviceName, this.config.serviceVersion ?? VERSION)
+		}
+		return this._meter
+	}
+
+	async start(): Promise<void> {
+		if (this.config.exporterType === 'none') {
+			logger.info('Telemetry disabled (exporterType=none)')
+			return
+		}
+
+		const resource = new Resource({
+			'service.name': this.config.serviceName,
+			'service.version': this.config.serviceVersion ?? VERSION,
+		})
+
+		const traceExporter =
+			this.config.exporterType === 'otlp'
+				? new OTLPTraceExporter({
+						url: this.config.otlpEndpoint ? `${this.config.otlpEndpoint}/v1/traces` : undefined,
+						headers: this.config.otlpHeaders,
+					})
+				: new ConsoleSpanExporter()
+
+		const metricExporter =
+			this.config.exporterType === 'otlp'
+				? new OTLPMetricExporter({
+						url: this.config.otlpEndpoint ? `${this.config.otlpEndpoint}/v1/metrics` : undefined,
+						headers: this.config.otlpHeaders,
+					})
+				: new ConsoleMetricExporter()
+
+		this.meterProvider = new MeterProvider({
+			resource,
+			readers: [
+				new PeriodicExportingMetricReader({
+					exporter: metricExporter,
+					exportIntervalMillis: this.config.metricExportIntervalMs ?? 10_000,
+				}),
+			],
+		})
+		metrics.setGlobalMeterProvider(this.meterProvider)
+
+		this.sdk = new NodeSDK({
+			resource,
+			spanProcessor: new SimpleSpanProcessor(traceExporter),
+		})
+
+		this.sdk.start()
+		logger.info(`Telemetry started (exporter=${this.config.exporterType})`)
+	}
+
+	async shutdown(): Promise<void> {
+		try {
+			if (this.meterProvider) {
+				await this.meterProvider.shutdown()
+			}
+			if (this.sdk) {
+				await this.sdk.shutdown()
+			}
+			logger.info('Telemetry shutdown complete')
+		} catch (err) {
+			logger.error('Telemetry shutdown error', {
+				error: toErrorMessage(err),
+			})
+		}
+	}
 }
 
 let _globalProvider: TelemetryProvider | null = null
 
 export function initTelemetry(config: TelemetryConfig): TelemetryProvider {
-  _globalProvider = new TelemetryProvider(config)
-  return _globalProvider
+	_globalProvider = new TelemetryProvider(config)
+	return _globalProvider
 }
 
 export function getTelemetry(): TelemetryProvider | null {
-  return _globalProvider
+	return _globalProvider
 }
 
 export function getTracer(): Tracer {
-  return _globalProvider?.tracer ?? trace.getTracer('namzu')
+	return _globalProvider?.tracer ?? trace.getTracer('namzu')
 }
 
 export function getMeter(): Meter {
-  return _globalProvider?.meter ?? metrics.getMeter('namzu')
+	return _globalProvider?.meter ?? metrics.getMeter('namzu')
 }

package/src/rag/chunking.ts

@@ -1,145 +1,135 @@
-import type { Chunker, ChunkContent, ChunkingConfig, ChunkingStrategy } from '../types/rag/index.js'
-
-const DEFAULT_SEPARATORS: Record<ChunkingStrategy, string[]> = {
-  fixed: [],
-  sentence: ['. ', '! ', '? ', '.\n', '!\n', '?\n'],
-  paragraph: ['\n\n', '\n'],
-  recursive: ['\n\n', '\n', '. ', ' ', ''],
-}
+import { DEFAULT_CHUNKING_CONFIG, DEFAULT_SEPARATORS } from '../constants/rag/index.js'
+import type { ChunkContent, Chunker, ChunkingConfig } from '../types/rag/index.js'
 
 export class TextChunker implements Chunker {
-  chunk(content: string, config: ChunkingConfig): ChunkContent[] {
-    switch (config.strategy) {
-      case 'fixed':
-        return this.fixedChunk(content, config)
-      case 'sentence':
-        return this.sentenceChunk(content, config)
-      case 'paragraph':
-        return this.paragraphChunk(content, config)
-      case 'recursive':
-        return this.recursiveChunk(content, config)
-      default: {
-        const _exhaustive: never = config.strategy
-        throw new Error(`Unhandled chunking strategy: ${_exhaustive}`)
-      }
-    }
-  }
-
-  private fixedChunk(content: string, config: ChunkingConfig): ChunkContent[] {
-    const { chunkSize, chunkOverlap } = config
-    const chunks: ChunkContent[] = []
-    const step = Math.max(1, chunkSize - chunkOverlap)
-    let idx = 0
-
-    for (let start = 0; start < content.length; start += step) {
-      const slice = content.slice(start, start + chunkSize).trim()
-      if (slice.length > 0) {
-        chunks.push({ content: slice, index: idx++ })
-      }
-    }
-    return chunks
-  }
-
-  private sentenceChunk(content: string, config: ChunkingConfig): ChunkContent[] {
-    const separators = config.separators ?? DEFAULT_SEPARATORS.sentence
-    const sentences = this.splitBySeparators(content, separators)
-    return this.mergeSmallParts(sentences, config)
-  }
-
-  private paragraphChunk(content: string, config: ChunkingConfig): ChunkContent[] {
-    const separators = config.separators ?? DEFAULT_SEPARATORS.paragraph
-    const paragraphs = this.splitBySeparators(content, separators)
-    return this.mergeSmallParts(paragraphs, config)
-  }
-
-  private recursiveChunk(content: string, config: ChunkingConfig): ChunkContent[] {
-    const separators = config.separators ?? DEFAULT_SEPARATORS.recursive
-    return this.recursiveSplit(content, separators, config, 0)
-  }
-
-  private recursiveSplit(
-    text: string,
-    separators: string[],
-    config: ChunkingConfig,
-    startIndex: number,
-  ): ChunkContent[] {
-    if (text.length <= config.chunkSize) {
-      const trimmed = text.trim()
-      return trimmed.length > 0 ? [{ content: trimmed, index: startIndex }] : []
-    }
-
-    for (const sep of separators) {
-      const parts = sep === '' ? [...text] : text.split(sep).filter(p => p.trim().length > 0)
-      if (parts.length <= 1) continue
-
-      const remaining = separators.slice(separators.indexOf(sep) + 1)
-      const merged = this.mergeSmallParts(parts, config)
-
-      if (merged.every(c => c.content.length <= config.chunkSize)) {
-        return merged
-      }
-
-      const results: ChunkContent[] = []
-      let idx = 0
-      for (const chunk of merged) {
-        if (chunk.content.length > config.chunkSize && remaining.length > 0) {
-          const subChunks = this.recursiveSplit(chunk.content, remaining, config, idx)
-          results.push(...subChunks)
-          idx += subChunks.length
-        } else {
-          results.push({ content: chunk.content, index: idx++ })
-        }
-      }
-      return results
-    }
-
-    return this.fixedChunk(text, config)
-  }
-
-  private splitBySeparators(text: string, separators: string[]): string[] {
-    let parts = [text]
-    for (const sep of separators) {
-      const nextParts: string[] = []
-      for (const part of parts) {
-        const splits = part.split(sep)
-        for (let i = 0; i < splits.length; i++) {
-          const piece = i < splits.length - 1 ? splits[i]! + sep : splits[i]!
-          if (piece.trim().length > 0) {
-            nextParts.push(piece)
-          }
-        }
-      }
-      parts = nextParts
-    }
-    return parts
-  }
-
-  private mergeSmallParts(parts: string[], config: ChunkingConfig): ChunkContent[] {
-    const { chunkSize, chunkOverlap } = config
-    const chunks: ChunkContent[] = []
-    let current = ''
-    let idx = 0
-
-    for (const part of parts) {
-      if (current.length + part.length > chunkSize && current.length > 0) {
-        chunks.push({ content: current.trim(), index: idx++ })
-        const overlapStart = Math.max(0, current.length - chunkOverlap)
-        current = current.slice(overlapStart) + part
-      } else {
-        current += part
-      }
-    }
-
-    if (current.trim().length > 0) {
-      chunks.push({ content: current.trim(), index: idx })
-    }
-
-    return chunks
-  }
+	chunk(content: string, config: ChunkingConfig): ChunkContent[] {
+		switch (config.strategy) {
+			case 'fixed':
+				return this.fixedChunk(content, config)
+			case 'sentence':
+				return this.sentenceChunk(content, config)
+			case 'paragraph':
+				return this.paragraphChunk(content, config)
+			case 'recursive':
+				return this.recursiveChunk(content, config)
+			default: {
+				const _exhaustive: never = config.strategy
+				throw new Error(`Unhandled chunking strategy: ${_exhaustive}`)
+			}
+		}
+	}
+
+	private fixedChunk(content: string, config: ChunkingConfig): ChunkContent[] {
+		const { chunkSize, chunkOverlap } = config
+		const chunks: ChunkContent[] = []
+		const step = Math.max(1, chunkSize - chunkOverlap)
+		let idx = 0
+
+		for (let start = 0; start < content.length; start += step) {
+			const slice = content.slice(start, start + chunkSize).trim()
+			if (slice.length > 0) {
+				chunks.push({ content: slice, index: idx++ })
+			}
+		}
+		return chunks
+	}
+
+	private sentenceChunk(content: string, config: ChunkingConfig): ChunkContent[] {
+		const separators = config.separators ?? DEFAULT_SEPARATORS.sentence
+		const sentences = this.splitBySeparators(content, separators)
+		return this.mergeSmallParts(sentences, config)
+	}
+
+	private paragraphChunk(content: string, config: ChunkingConfig): ChunkContent[] {
+		const separators = config.separators ?? DEFAULT_SEPARATORS.paragraph
+		const paragraphs = this.splitBySeparators(content, separators)
+		return this.mergeSmallParts(paragraphs, config)
+	}
+
+	private recursiveChunk(content: string, config: ChunkingConfig): ChunkContent[] {
+		const separators = config.separators ?? DEFAULT_SEPARATORS.recursive
+		return this.recursiveSplit(content, separators, config, 0)
+	}
+
+	private recursiveSplit(
+		text: string,
+		separators: string[],
+		config: ChunkingConfig,
+		startIndex: number,
+	): ChunkContent[] {
+		if (text.length <= config.chunkSize) {
+			const trimmed = text.trim()
+			return trimmed.length > 0 ? [{ content: trimmed, index: startIndex }] : []
+		}
+
+		for (const sep of separators) {
+			const parts = sep === '' ? [...text] : text.split(sep).filter((p) => p.trim().length > 0)
+			if (parts.length <= 1) continue
+
+			const remaining = separators.slice(separators.indexOf(sep) + 1)
+			const merged = this.mergeSmallParts(parts, config)
+
+			if (merged.every((c) => c.content.length <= config.chunkSize)) {
+				return merged
+			}
+
+			const results: ChunkContent[] = []
+			let idx = 0
+			for (const chunk of merged) {
+				if (chunk.content.length > config.chunkSize && remaining.length > 0) {
+					const subChunks = this.recursiveSplit(chunk.content, remaining, config, idx)
+					results.push(...subChunks)
+					idx += subChunks.length
+				} else {
+					results.push({ content: chunk.content, index: idx++ })
+				}
+			}
+			return results
+		}
+
+		return this.fixedChunk(text, config)
+	}
+
+	private splitBySeparators(text: string, separators: string[]): string[] {
+		let parts = [text]
+		for (const sep of separators) {
+			const nextParts: string[] = []
+			for (const part of parts) {
+				const splits = part.split(sep)
+				for (const [i, segment] of splits.entries()) {
+					const piece = i < splits.length - 1 ? segment + sep : segment
+					if (piece.trim().length > 0) {
+						nextParts.push(piece)
+					}
+				}
+			}
+			parts = nextParts
+		}
+		return parts
+	}
+
+	private mergeSmallParts(parts: string[], config: ChunkingConfig): ChunkContent[] {
+		const { chunkSize, chunkOverlap } = config
+		const chunks: ChunkContent[] = []
+		let current = ''
+		let idx = 0
+
+		for (const part of parts) {
+			if (current.length + part.length > chunkSize && current.length > 0) {
+				chunks.push({ content: current.trim(), index: idx++ })
+				const overlapStart = Math.max(0, current.length - chunkOverlap)
+				current = current.slice(overlapStart) + part
+			} else {
+				current += part
+			}
+		}
+
+		if (current.trim().length > 0) {
+			chunks.push({ content: current.trim(), index: idx })
+		}
+
+		return chunks
+	}
 }
 
-export const DEFAULT_CHUNKING_CONFIG: ChunkingConfig = {
-  strategy: 'recursive',
-  chunkSize: 512,
-  chunkOverlap: 64,
-}
+export { DEFAULT_CHUNKING_CONFIG }

package/src/rag/context-assembler.ts

@@ -1,65 +1,61 @@
+import { DEFAULT_RAG_CONTEXT_CONFIG } from '../constants/rag/index.js'
 import type { RAGContext, RAGContextConfig, VectorSearchResult } from '../types/rag/index.js'
 
-export const DEFAULT_RAG_CONTEXT_CONFIG: RAGContextConfig = {
-  maxTokens: 4096,
-  separator: '\n\n---\n\n',
-  includeMetadata: true,
-  headerTemplate: '## Retrieved Knowledge\n\nThe following information was retrieved from the knowledge base:\n',
-}
+export { DEFAULT_RAG_CONTEXT_CONFIG }
 
 export function assembleRAGContext(
-  results: VectorSearchResult[],
-  config: Partial<RAGContextConfig> = {},
+	results: VectorSearchResult[],
+	config: Partial<RAGContextConfig> = {},
 ): RAGContext {
-  const effectiveConfig = { ...DEFAULT_RAG_CONTEXT_CONFIG, ...config }
+	const effectiveConfig = { ...DEFAULT_RAG_CONTEXT_CONFIG, ...config }
 
-  if (results.length === 0) {
-    return { content: '', sources: [], tokenCount: 0 }
-  }
+	if (results.length === 0) {
+		return { content: '', sources: [], tokenCount: 0 }
+	}
 
-  const sources: RAGContext['sources'] = []
-  const parts: string[] = []
+	const sources: RAGContext['sources'] = []
+	const parts: string[] = []
 
-  if (effectiveConfig.headerTemplate) {
-    parts.push(effectiveConfig.headerTemplate)
-  }
+	if (effectiveConfig.headerTemplate) {
+		parts.push(effectiveConfig.headerTemplate)
+	}
 
-  let currentTokens = estimateTokens(parts.join(''))
+	let currentTokens = estimateTokens(parts.join(''))
 
-  for (const result of results) {
-    const chunkTokens = estimateTokens(result.chunk.content)
-    if (currentTokens + chunkTokens > effectiveConfig.maxTokens) break
+	for (const result of results) {
+		const chunkTokens = estimateTokens(result.chunk.content)
+		if (currentTokens + chunkTokens > effectiveConfig.maxTokens) break
 
-    let entry = result.chunk.content
+		let entry = result.chunk.content
 
-    if (effectiveConfig.includeMetadata) {
-      const meta = formatMetadata(result)
-      entry = `${meta}\n${entry}`
-    }
+		if (effectiveConfig.includeMetadata) {
+			const meta = formatMetadata(result)
+			entry = `${meta}\n${entry}`
+		}
 
-    parts.push(entry)
-    currentTokens += chunkTokens
+		parts.push(entry)
+		currentTokens += chunkTokens
 
-    sources.push({
-      documentId: result.chunk.documentId,
-      chunk: result.chunk.content.slice(0, 200),
-      score: result.score,
-    })
-  }
+		sources.push({
+			documentId: result.chunk.documentId,
+			chunk: result.chunk.content.slice(0, 200),
+			score: result.score,
+		})
+	}
 
-  const content = parts.join(effectiveConfig.separator)
-  return { content, sources, tokenCount: estimateTokens(content) }
+	const content = parts.join(effectiveConfig.separator)
+	return { content, sources, tokenCount: estimateTokens(content) }
 }
 
 function formatMetadata(result: VectorSearchResult): string {
-  const meta = result.chunk.metadata
-  const parts: string[] = []
-  if (meta.source) parts.push(`Source: ${meta.source}`)
-  if (meta.title) parts.push(`Title: ${meta.title}`)
-  parts.push(`Relevance: ${(result.score * 100).toFixed(1)}%`)
-  return `[${parts.join(' | ')}]`
+	const meta = result.chunk.metadata
+	const parts: string[] = []
+	if (meta.source) parts.push(`Source: ${meta.source}`)
+	if (meta.title) parts.push(`Title: ${meta.title}`)
+	parts.push(`Relevance: ${(result.score * 100).toFixed(1)}%`)
+	return `[${parts.join(' | ')}]`
 }
 
 function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4)
+	return Math.ceil(text.length / 4)
 }