@dangao/bun-server 1.12.0 → 2.0.0

package/src/rag/service.ts

@@ -0,0 +1,134 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type { EmbeddingService } from '../embedding/service';
+import { EMBEDDING_SERVICE_TOKEN } from '../embedding/types';
+import type { VectorStore } from '../vector-store/types';
+import { VECTOR_STORE_TOKEN } from '../vector-store/types';
+import type { IngestSource, RagContext, RagModuleOptions, DocumentChunker } from './types';
+import { RAG_OPTIONS_TOKEN } from './types';
+import { TextChunker } from './chunkers/text-chunker';
+import { MarkdownChunker } from './chunkers/markdown-chunker';
+
+/**
+ * RAG service — document ingestion pipeline and context retrieval.
+ *
+ * Ingestion: source → load text → chunk → embed → store in VectorStore
+ * Retrieval: query → embed → search VectorStore → format context
+ */
+@Injectable()
+export class RagService {
+  private readonly options: RagModuleOptions;
+  private readonly embeddingService: EmbeddingService;
+  private readonly vectorStore: VectorStore;
+  private readonly textChunker: DocumentChunker;
+  private readonly markdownChunker: DocumentChunker;
+
+  public constructor(
+    @Inject(RAG_OPTIONS_TOKEN) options: RagModuleOptions,
+    @Inject(EMBEDDING_SERVICE_TOKEN) embeddingService: EmbeddingService,
+    @Inject(VECTOR_STORE_TOKEN) vectorStore: VectorStore,
+  ) {
+    this.options = options;
+    this.embeddingService = embeddingService;
+    this.vectorStore = vectorStore;
+    this.textChunker = new TextChunker(options.chunkSize, options.chunkOverlap);
+    this.markdownChunker = new MarkdownChunker(options.chunkSize);
+  }
+
+  /**
+   * Ingest a document source into the vector store
+   * @param source - text, file path, or URL
+   * @param collection - override default collection
+   * @returns Number of chunks stored
+   */
+  public async ingest(source: IngestSource, collection?: string): Promise<number> {
+    const targetCollection = collection ?? this.options.collection ?? 'rag';
+    const text = await this.loadText(source);
+
+    if (!text.trim()) return 0;
+
+    // Choose chunker based on content type
+    const isMarkdown = source.type === 'file' && (source.path.endsWith('.md') || source.path.endsWith('.mdx'));
+    const chunker = isMarkdown ? this.markdownChunker : this.textChunker;
+    const chunks = chunker.chunk(text);
+
+    // Batch embed all chunks
+    const vectors = await this.embeddingService.embedBatch(chunks.map((c) => c.content));
+
+    // Store in vector store
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i]!;
+      const vector = vectors[i]!;
+      await this.vectorStore.upsert({
+        id: crypto.randomUUID(),
+        vector,
+        content: chunk.content,
+        collection: targetCollection,
+        metadata: {
+          ...(chunk.metadata ?? {}),
+          ...(source.metadata ?? {}),
+          sourceType: source.type,
+          ...(source.type === 'file' ? { sourcePath: source.path } : {}),
+          ...(source.type === 'url' ? { sourceUrl: source.url } : {}),
+        },
+      });
+    }
+
+    return chunks.length;
+  }
+
+  /**
+   * Retrieve relevant context for a query
+   * @param query - User query text
+   * @param collection - override default collection
+   */
+  public async retrieve(query: string, collection?: string): Promise<RagContext> {
+    const targetCollection = collection ?? this.options.collection ?? 'rag';
+    const queryVector = await this.embeddingService.embed(query);
+
+    const results = await this.vectorStore.search(queryVector, {
+      topK: this.options.topK ?? 5,
+      minScore: this.options.minScore ?? 0.5,
+      collection: targetCollection,
+    });
+
+    const chunks = results.map((r) => ({
+      content: r.document.content,
+      score: r.score,
+      metadata: r.document.metadata,
+    }));
+
+    const formatted = chunks.length > 0
+      ? chunks.map((c, i) => `[${i + 1}] ${c.content}`).join('\n\n')
+      : '';
+
+    return { chunks, formatted };
+  }
+
+  /**
+   * Build a system prompt with retrieved context
+   */
+  public async buildContextPrompt(query: string, collection?: string): Promise<string> {
+    const context = await this.retrieve(query, collection);
+    if (!context.formatted) return '';
+    return `Use the following context to answer the question:\n\n${context.formatted}`;
+  }
+
+  private async loadText(source: IngestSource): Promise<string> {
+    switch (source.type) {
+      case 'text':
+        return source.content;
+
+      case 'file': {
+        const file = Bun.file(source.path);
+        return file.text();
+      }
+
+      case 'url': {
+        const res = await fetch(source.url);
+        if (!res.ok) throw new Error(`Failed to fetch ${source.url}: ${res.status}`);
+        return res.text();
+      }
+    }
+  }
+}

package/src/rag/types.ts

@@ -0,0 +1,47 @@
+/**
+ * A chunk of text produced by a document chunker
+ */
+export interface DocumentChunk {
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Source for document ingestion
+ */
+export type IngestSource =
+  | { type: 'text'; content: string; metadata?: Record<string, unknown> }
+  | { type: 'file'; path: string; metadata?: Record<string, unknown> }
+  | { type: 'url'; url: string; metadata?: Record<string, unknown> };
+
+/**
+ * Abstract document chunker
+ */
+export interface DocumentChunker {
+  chunk(text: string): DocumentChunk[];
+}
+
+/**
+ * Retrieved context for RAG
+ */
+export interface RagContext {
+  chunks: Array<{ content: string; score: number; metadata?: Record<string, unknown> }>;
+  /** Formatted context string for inclusion in prompts */
+  formatted: string;
+}
+
+export interface RagModuleOptions {
+  /** Collection name in VectorStore (default: 'rag') */
+  collection?: string;
+  /** Number of chunks per ingested document (default: 512) */
+  chunkSize?: number;
+  /** Overlap between consecutive chunks (default: 50) */
+  chunkOverlap?: number;
+  /** Number of top results to retrieve (default: 5) */
+  topK?: number;
+  /** Minimum similarity score to include (default: 0.5) */
+  minScore?: number;
+}
+
+export const RAG_SERVICE_TOKEN = Symbol('@dangao/bun-server:rag:service');
+export const RAG_OPTIONS_TOKEN = Symbol('@dangao/bun-server:rag:options');

package/src/vector-store/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './vector-store-module';
+export * from './stores/memory-store';
+export * from './stores/pinecone-store';
+export * from './stores/qdrant-store';

package/src/vector-store/stores/memory-store.ts

@@ -0,0 +1,69 @@
+import type { VectorStore, VectorDocument, VectorSearchResult, VectorSearchOptions } from '../types';
+import { cosineSimilarity } from '../types';
+
+/**
+ * High-performance in-memory vector store using cosine similarity.
+ * Suitable for development and small to medium datasets (up to ~100K documents).
+ */
+export class MemoryVectorStore implements VectorStore {
+  private readonly documents = new Map<string, VectorDocument>();
+
+  public async upsert(document: VectorDocument): Promise<void> {
+    this.documents.set(this.key(document.id, document.collection), document);
+  }
+
+  public async upsertBatch(documents: VectorDocument[]): Promise<void> {
+    for (const doc of documents) {
+      this.documents.set(this.key(doc.id, doc.collection), doc);
+    }
+  }
+
+  public async get(id: string, collection?: string): Promise<VectorDocument | null> {
+    return this.documents.get(this.key(id, collection)) ?? null;
+  }
+
+  public async search(query: number[], options: VectorSearchOptions = {}): Promise<VectorSearchResult[]> {
+    const { topK = 5, minScore = 0, collection, filter } = options;
+
+    const results: VectorSearchResult[] = [];
+
+    for (const doc of this.documents.values()) {
+      if (collection && doc.collection !== collection) continue;
+      if (filter && !filter(doc)) continue;
+
+      const score = cosineSimilarity(query, doc.vector);
+      if (score >= minScore) {
+        results.push({ document: doc, score });
+      }
+    }
+
+    return results
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK);
+  }
+
+  public async delete(id: string, collection?: string): Promise<boolean> {
+    return this.documents.delete(this.key(id, collection));
+  }
+
+  public async deleteCollection(collection: string): Promise<void> {
+    for (const [key, doc] of this.documents.entries()) {
+      if (doc.collection === collection) {
+        this.documents.delete(key);
+      }
+    }
+  }
+
+  public async count(collection?: string): Promise<number> {
+    if (!collection) return this.documents.size;
+    let count = 0;
+    for (const doc of this.documents.values()) {
+      if (doc.collection === collection) count++;
+    }
+    return count;
+  }
+
+  private key(id: string, collection?: string): string {
+    return collection ? `${collection}:${id}` : id;
+  }
+}

package/src/vector-store/stores/pinecone-store.ts

@@ -0,0 +1,123 @@
+import type { VectorStore, VectorDocument, VectorSearchResult, VectorSearchOptions } from '../types';
+
+export interface PineconeStoreConfig {
+  apiKey: string;
+  /** Pinecone host URL (e.g., https://my-index-xxxx.svc.aped-xxxx.pinecone.io) */
+  host: string;
+  /** Namespace (optional) */
+  namespace?: string;
+}
+
+/**
+ * Pinecone vector store adapter.
+ * Uses the Pinecone REST API directly — no SDK dependency.
+ */
+export class PineconeVectorStore implements VectorStore {
+  private readonly apiKey: string;
+  private readonly host: string;
+  private readonly namespace: string;
+
+  public constructor(config: PineconeStoreConfig) {
+    this.apiKey = config.apiKey;
+    this.host = config.host.replace(/\/$/, '');
+    this.namespace = config.namespace ?? '';
+  }
+
+  public async upsert(document: VectorDocument): Promise<void> {
+    await this.upsertBatch([document]);
+  }
+
+  public async upsertBatch(documents: VectorDocument[]): Promise<void> {
+    const vectors = documents.map((d) => ({
+      id: d.id,
+      values: d.vector,
+      metadata: { content: d.content, collection: d.collection ?? '', ...d.metadata },
+    }));
+
+    await this.request('/vectors/upsert', 'POST', { vectors, namespace: this.namespace });
+  }
+
+  public async get(id: string): Promise<VectorDocument | null> {
+    const res = await this.request<{ vectors: Record<string, unknown> }>(
+      `/vectors/fetch?ids=${encodeURIComponent(id)}&namespace=${this.namespace}`,
+      'GET',
+    );
+    const vector = res?.['vectors']?.[id] as Record<string, unknown> | undefined;
+    if (!vector) return null;
+    const metadata = (vector['metadata'] as Record<string, unknown>) ?? {};
+    return {
+      id,
+      vector: vector['values'] as number[],
+      content: (metadata['content'] as string) ?? '',
+      collection: (metadata['collection'] as string) || undefined,
+      metadata,
+    };
+  }
+
+  public async search(query: number[], options: VectorSearchOptions = {}): Promise<VectorSearchResult[]> {
+    const { topK = 5, collection } = options;
+    const filter = collection ? { collection: { $eq: collection } } : undefined;
+
+    const res = await this.request<{ matches: Array<Record<string, unknown>> }>(
+      '/query',
+      'POST',
+      {
+        vector: query,
+        topK,
+        includeMetadata: true,
+        namespace: this.namespace,
+        filter,
+      },
+    );
+
+    return (res?.['matches'] ?? []).map((match) => {
+      const metadata = (match['metadata'] as Record<string, unknown>) ?? {};
+      return {
+        document: {
+          id: match['id'] as string,
+          vector: [],
+          content: (metadata['content'] as string) ?? '',
+          collection: (metadata['collection'] as string) || undefined,
+          metadata,
+        },
+        score: match['score'] as number,
+      };
+    });
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    await this.request('/vectors/delete', 'POST', { ids: [id], namespace: this.namespace });
+    return true;
+  }
+
+  public async deleteCollection(collection: string): Promise<void> {
+    await this.request('/vectors/delete', 'POST', {
+      deleteAll: false,
+      namespace: this.namespace,
+      filter: { collection: { $eq: collection } },
+    });
+  }
+
+  public async count(): Promise<number> {
+    const res = await this.request<{ namespaces: Record<string, { vectorCount: number }> }>(
+      '/describe_index_stats',
+      'POST',
+      {},
+    );
+    const ns = res?.['namespaces']?.[this.namespace];
+    return ns?.vectorCount ?? 0;
+  }
+
+  private async request<T = unknown>(path: string, method: string, body?: unknown): Promise<T | null> {
+    const res = await fetch(`${this.host}${path}`, {
+      method,
+      headers: {
+        'Api-Key': this.apiKey,
+        'Content-Type': 'application/json',
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) return null;
+    return res.json() as Promise<T>;
+  }
+}

package/src/vector-store/stores/qdrant-store.ts

@@ -0,0 +1,147 @@
+import type { VectorStore, VectorDocument, VectorSearchResult, VectorSearchOptions } from '../types';
+
+export interface QdrantStoreConfig {
+  /** Qdrant server URL (default: http://localhost:6333) */
+  url?: string;
+  /** Collection name in Qdrant */
+  collectionName: string;
+  /** API key (optional, for Qdrant Cloud) */
+  apiKey?: string;
+}
+
+/**
+ * Qdrant vector store adapter.
+ * Uses the Qdrant REST API directly — no SDK dependency.
+ */
+export class QdrantVectorStore implements VectorStore {
+  private readonly url: string;
+  private readonly collectionName: string;
+  private readonly apiKey: string | undefined;
+
+  public constructor(config: QdrantStoreConfig) {
+    this.url = (config.url ?? 'http://localhost:6333').replace(/\/$/, '');
+    this.collectionName = config.collectionName;
+    this.apiKey = config.apiKey;
+  }
+
+  public async upsert(document: VectorDocument): Promise<void> {
+    await this.upsertBatch([document]);
+  }
+
+  public async upsertBatch(documents: VectorDocument[]): Promise<void> {
+    const points = documents.map((d, idx) => ({
+      id: this.toNumericId(d.id) ?? idx,
+      vector: d.vector,
+      payload: {
+        original_id: d.id,
+        content: d.content,
+        collection: d.collection ?? '',
+        ...(d.metadata ?? {}),
+      },
+    }));
+
+    await this.request(`/collections/${this.collectionName}/points`, 'PUT', { points });
+  }
+
+  public async get(id: string): Promise<VectorDocument | null> {
+    const numId = this.toNumericId(id);
+    if (!numId) return null;
+
+    const res = await this.request<{ result: Record<string, unknown> | null }>(
+      `/collections/${this.collectionName}/points/${numId}`,
+      'GET',
+    );
+    const point = res?.['result'];
+    if (!point) return null;
+
+    const payload = (point['payload'] as Record<string, unknown>) ?? {};
+    return {
+      id: (payload['original_id'] as string) ?? id,
+      vector: (point['vector'] as number[]) ?? [],
+      content: (payload['content'] as string) ?? '',
+      collection: (payload['collection'] as string) || undefined,
+      metadata: payload,
+    };
+  }
+
+  public async search(query: number[], options: VectorSearchOptions = {}): Promise<VectorSearchResult[]> {
+    const { topK = 5, minScore = 0, collection } = options;
+
+    const body: Record<string, unknown> = {
+      vector: query,
+      limit: topK,
+      with_payload: true,
+      score_threshold: minScore,
+    };
+
+    if (collection) {
+      body['filter'] = { must: [{ key: 'collection', match: { value: collection } }] };
+    }
+
+    const res = await this.request<{ result: Array<Record<string, unknown>> }>(
+      `/collections/${this.collectionName}/points/search`,
+      'POST',
+      body,
+    );
+
+    return (res?.['result'] ?? []).map((hit) => {
+      const payload = (hit['payload'] as Record<string, unknown>) ?? {};
+      return {
+        document: {
+          id: (payload['original_id'] as string) ?? String(hit['id']),
+          vector: [],
+          content: (payload['content'] as string) ?? '',
+          collection: (payload['collection'] as string) || undefined,
+          metadata: payload,
+        },
+        score: hit['score'] as number,
+      };
+    });
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    const numId = this.toNumericId(id);
+    if (!numId) return false;
+    await this.request(
+      `/collections/${this.collectionName}/points/delete`,
+      'POST',
+      { points: [numId] },
+    );
+    return true;
+  }
+
+  public async deleteCollection(collection: string): Promise<void> {
+    await this.request(
+      `/collections/${this.collectionName}/points/delete`,
+      'POST',
+      { filter: { must: [{ key: 'collection', match: { value: collection } }] } },
+    );
+  }
+
+  public async count(): Promise<number> {
+    const res = await this.request<{ result: { count: number } }>(
+      `/collections/${this.collectionName}/points/count`,
+      'POST',
+      {},
+    );
+    return res?.['result']?.count ?? 0;
+  }
+
+  private toNumericId(id: string): number | null {
+    const n = parseInt(id, 10);
+    return isNaN(n) ? null : n;
+  }
+
+  private async request<T = unknown>(path: string, method: string, body?: unknown): Promise<T | null> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (this.apiKey) headers['api-key'] = this.apiKey;
+
+    const res = await fetch(`${this.url}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) return null;
+    return res.json() as Promise<T>;
+  }
+}

package/src/vector-store/types.ts

@@ -0,0 +1,77 @@
+/**
+ * A document stored in the vector store
+ */
+export interface VectorDocument {
+  id: string;
+  /** The embedding vector */
+  vector: number[];
+  /** Original text content */
+  content: string;
+  /** Arbitrary metadata */
+  metadata?: Record<string, unknown>;
+  /** Collection / namespace */
+  collection?: string;
+}
+
+/**
+ * Search result with similarity score
+ */
+export interface VectorSearchResult {
+  document: VectorDocument;
+  /** Cosine similarity score [0, 1] */
+  score: number;
+}
+
+/**
+ * Search options
+ */
+export interface VectorSearchOptions {
+  topK?: number;
+  minScore?: number;
+  collection?: string;
+  filter?: (doc: VectorDocument) => boolean;
+}
+
+/**
+ * Abstract vector store interface
+ */
+export interface VectorStore {
+  /** Insert or update a document */
+  upsert(document: VectorDocument): Promise<void>;
+  /** Insert or update multiple documents */
+  upsertBatch(documents: VectorDocument[]): Promise<void>;
+  /** Retrieve a document by ID */
+  get(id: string, collection?: string): Promise<VectorDocument | null>;
+  /** Search for similar documents using cosine similarity */
+  search(query: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+  /** Delete a document by ID */
+  delete(id: string, collection?: string): Promise<boolean>;
+  /** Delete all documents in a collection */
+  deleteCollection(collection: string): Promise<void>;
+  /** Count documents */
+  count(collection?: string): Promise<number>;
+}
+
+export interface VectorStoreModuleOptions {
+  store?: VectorStore;
+}
+
+export const VECTOR_STORE_TOKEN = Symbol('@dangao/bun-server:vector-store:store');
+export const VECTOR_STORE_OPTIONS_TOKEN = Symbol('@dangao/bun-server:vector-store:options');
+
+/**
+ * Compute cosine similarity between two vectors
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}

package/src/vector-store/vector-store-module.ts

@@ -0,0 +1,50 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import {
+  VECTOR_STORE_TOKEN,
+  VECTOR_STORE_OPTIONS_TOKEN,
+  type VectorStoreModuleOptions,
+} from './types';
+import { MemoryVectorStore } from './stores/memory-store';
+
+@Module({ providers: [] })
+export class VectorStoreModule {
+  /**
+   * Configure the vector store module.
+   *
+   * @example
+   * ```typescript
+   * // Built-in memory store (default):
+   * VectorStoreModule.forRoot({});
+   *
+   * // Pinecone:
+   * VectorStoreModule.forRoot({
+   *   store: new PineconeVectorStore({ apiKey: '...', host: '...' }),
+   * });
+   * ```
+   */
+  public static forRoot(options: VectorStoreModuleOptions = {}): typeof VectorStoreModule {
+    const store = options.store ?? new MemoryVectorStore();
+
+    const providers: ModuleProvider[] = [
+      { provide: VECTOR_STORE_OPTIONS_TOKEN, useValue: options },
+      { provide: VECTOR_STORE_TOKEN, useValue: store },
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, VectorStoreModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        VECTOR_STORE_TOKEN,
+      ],
+    }, VectorStoreModule);
+
+    return VectorStoreModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, VectorStoreModule);
+  }
+}