@dangao/bun-server 1.12.1 → 2.0.1

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

@@ -0,0 +1,82 @@
+import type {
+  PromptStore,
+  PromptTemplate,
+  CreatePromptTemplateInput,
+  UpdatePromptTemplateInput,
+} from '../types';
+import { extractVariables } from '../types';
+
+/**
+ * In-memory prompt store. Supports versioning via a separate history map.
+ */
+export class InMemoryPromptStore implements PromptStore {
+  private readonly templates = new Map<string, PromptTemplate>();
+  /** id → version → template snapshot */
+  private readonly history = new Map<string, Map<number, PromptTemplate>>();
+
+  public async get(id: string): Promise<PromptTemplate | null> {
+    return this.templates.get(id) ?? null;
+  }
+
+  public async getVersion(id: string, version: number): Promise<PromptTemplate | null> {
+    return this.history.get(id)?.get(version) ?? null;
+  }
+
+  public async list(): Promise<PromptTemplate[]> {
+    return Array.from(this.templates.values());
+  }
+
+  public async create(input: CreatePromptTemplateInput): Promise<PromptTemplate> {
+    const id = input.id ?? crypto.randomUUID();
+    if (this.templates.has(id)) {
+      throw new Error(`Prompt template "${id}" already exists`);
+    }
+    const now = new Date();
+    const template: PromptTemplate = {
+      id,
+      name: input.name,
+      content: input.content,
+      version: 1,
+      variables: extractVariables(input.content),
+      description: input.description,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.templates.set(id, template);
+    this.saveVersion(template);
+    return { ...template };
+  }
+
+  public async update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate> {
+    const existing = this.templates.get(id);
+    if (!existing) throw new Error(`Prompt template "${id}" not found`);
+
+    const now = new Date();
+    const content = input.content ?? existing.content;
+    const updated: PromptTemplate = {
+      ...existing,
+      name: input.name ?? existing.name,
+      content,
+      description: input.description ?? existing.description,
+      version: existing.version + 1,
+      variables: extractVariables(content),
+      updatedAt: now,
+    };
+    this.templates.set(id, updated);
+    this.saveVersion(updated);
+    return { ...updated };
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    const existed = this.templates.delete(id);
+    this.history.delete(id);
+    return existed;
+  }
+
+  private saveVersion(template: PromptTemplate): void {
+    if (!this.history.has(template.id)) {
+      this.history.set(template.id, new Map());
+    }
+    this.history.get(template.id)!.set(template.version, { ...template });
+  }
+}

package/src/prompt/types.ts

@@ -0,0 +1,84 @@
+/**
+ * A versioned prompt template with variable interpolation
+ */
+export interface PromptTemplate {
+  id: string;
+  name: string;
+  /** Template content with {{variable}} placeholders */
+  content: string;
+  /** Current version number (starts at 1, increments on each update) */
+  version: number;
+  /** Declared variable names (auto-extracted from content) */
+  variables: string[];
+  /** Optional description */
+  description?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Input for creating a prompt template
+ */
+export interface CreatePromptTemplateInput {
+  id?: string;
+  name: string;
+  content: string;
+  description?: string;
+}
+
+/**
+ * Input for updating a prompt template (creates new version)
+ */
+export interface UpdatePromptTemplateInput {
+  name?: string;
+  content?: string;
+  description?: string;
+}
+
+/**
+ * Abstract prompt store interface
+ */
+export interface PromptStore {
+  get(id: string): Promise<PromptTemplate | null>;
+  getVersion(id: string, version: number): Promise<PromptTemplate | null>;
+  list(): Promise<PromptTemplate[]>;
+  create(input: CreatePromptTemplateInput): Promise<PromptTemplate>;
+  update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate>;
+  delete(id: string): Promise<boolean>;
+}
+
+/**
+ * PromptModule configuration
+ */
+export interface PromptModuleOptions {
+  store?: PromptStore;
+  /**
+   * Preload templates on module init
+   * (only used by FilePromptStore, which loads from promptsDir)
+   */
+  promptsDir?: string;
+}
+
+export const PROMPT_SERVICE_TOKEN = Symbol('@dangao/bun-server:prompt:service');
+export const PROMPT_OPTIONS_TOKEN = Symbol('@dangao/bun-server:prompt:options');
+
+/**
+ * Extract variable names from template content
+ * Matches {{varName}} patterns
+ */
+export function extractVariables(content: string): string[] {
+  const regex = /\{\{(\w+)\}\}/g;
+  const vars = new Set<string>();
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null) {
+    vars.add(match[1]!);
+  }
+  return Array.from(vars);
+}
+
+/**
+ * Render a template by replacing {{varName}} with provided values
+ */
+export function renderTemplate(content: string, vars: Record<string, string>): string {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key: string) => vars[key] ?? `{{${key}}}`);
+}

package/src/rag/chunkers/markdown-chunker.ts

@@ -0,0 +1,40 @@
+import type { DocumentChunker, DocumentChunk } from '../types';
+
+/**
+ * Splits Markdown text into semantic chunks by heading boundaries.
+ * Falls back to text chunking for sections that are too large.
+ */
+export class MarkdownChunker implements DocumentChunker {
+  private readonly maxChunkSize: number;
+
+  public constructor(maxChunkSize = 1024) {
+    this.maxChunkSize = maxChunkSize;
+  }
+
+  public chunk(text: string): DocumentChunk[] {
+    const chunks: DocumentChunk[] = [];
+    // Split on headings (## or ###)
+    const sections = text.split(/(?=^#{1,3} )/m).filter((s) => s.trim());
+
+    for (const section of sections) {
+      if (section.length <= this.maxChunkSize) {
+        chunks.push({ content: section.trim() });
+      } else {
+        // Split large sections into paragraphs
+        const paragraphs = section.split(/\n\n+/).filter((p) => p.trim());
+        let current = '';
+        for (const para of paragraphs) {
+          if ((current + '\n\n' + para).length > this.maxChunkSize && current) {
+            chunks.push({ content: current.trim() });
+            current = para;
+          } else {
+            current = current ? current + '\n\n' + para : para;
+          }
+        }
+        if (current.trim()) chunks.push({ content: current.trim() });
+      }
+    }
+
+    return chunks.length > 0 ? chunks : [{ content: text.trim() }];
+  }
+}

package/src/rag/chunkers/text-chunker.ts

@@ -0,0 +1,30 @@
+import type { DocumentChunker, DocumentChunk } from '../types';
+
+/**
+ * Splits plain text into overlapping chunks of fixed character size.
+ */
+export class TextChunker implements DocumentChunker {
+  private readonly chunkSize: number;
+  private readonly chunkOverlap: number;
+
+  public constructor(chunkSize = 512, chunkOverlap = 50) {
+    this.chunkSize = chunkSize;
+    this.chunkOverlap = chunkOverlap;
+  }
+
+  public chunk(text: string): DocumentChunk[] {
+    const chunks: DocumentChunk[] = [];
+    const step = this.chunkSize - this.chunkOverlap;
+
+    for (let start = 0; start < text.length; start += step) {
+      const end = Math.min(start + this.chunkSize, text.length);
+      const content = text.slice(start, end).trim();
+      if (content.length > 0) {
+        chunks.push({ content });
+      }
+      if (end >= text.length) break;
+    }
+
+    return chunks;
+  }
+}

package/src/rag/decorators.ts

@@ -0,0 +1,26 @@
+/**
+ * Metadata key for @Rag() decorator
+ */
+export const RAG_METADATA_KEY = '@dangao/bun-server:rag:collection';
+
+/**
+ * Mark a controller method to auto-retrieve RAG context before execution.
+ * The retrieved context is available via `@Inject(RAG_SERVICE_TOKEN)` in the service layer.
+ *
+ * @param collection - VectorStore collection to search (uses default if omitted)
+ *
+ * @example
+ * ```typescript
+ * \@POST('/ask')
+ * \@Rag({ collection: 'product-docs' })
+ * public async ask(\@Body() body: { question: string }) {
+ *   // RAG context is automatically fetched before this method
+ *   // Access via RagService.retrieve() in your service
+ * }
+ * ```
+ */
+export function Rag(options: { collection?: string } = {}): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(RAG_METADATA_KEY, options, target, propertyKey);
+  };
+}

package/src/rag/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './service';
+export * from './decorators';
+export * from './rag-module';
+export * from './chunkers/text-chunker';
+export * from './chunkers/markdown-chunker';

package/src/rag/rag-module.ts

@@ -0,0 +1,78 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import type { Container } from '../di/container';
+import { RagService } from './service';
+import { RAG_SERVICE_TOKEN, RAG_OPTIONS_TOKEN, type RagModuleOptions } from './types';
+import { EMBEDDING_SERVICE_TOKEN } from '../embedding/types';
+import { VECTOR_STORE_TOKEN } from '../vector-store/types';
+import { EmbeddingModule } from '../embedding/embedding-module';
+import { VectorStoreModule } from '../vector-store/vector-store-module';
+
+@Module({
+  imports: [EmbeddingModule, VectorStoreModule],
+  providers: [],
+})
+export class RagModule {
+  /**
+   * Configure the RAG module.
+   *
+   * **Requires** `EmbeddingModule` and `VectorStoreModule` to be imported first.
+   *
+   * @example
+   * ```typescript
+   * EmbeddingModule.forRoot({ provider: { ... } });
+   * VectorStoreModule.forRoot({});
+   * RagModule.forRoot({ collection: 'docs', chunkSize: 512, topK: 5 });
+   *
+   * \@Module({
+   *   imports: [EmbeddingModule, VectorStoreModule, RagModule],
+   * })
+   * class AppModule {}
+   * ```
+   */
+  public static forRoot(options: RagModuleOptions = {}): typeof RagModule {
+    const resolvedOptions: RagModuleOptions = {
+      collection: 'rag',
+      chunkSize: 512,
+      chunkOverlap: 50,
+      topK: 5,
+      minScore: 0.5,
+      ...options,
+    };
+
+    const providers: ModuleProvider[] = [
+      { provide: RAG_OPTIONS_TOKEN, useValue: resolvedOptions },
+      {
+        provide: RAG_SERVICE_TOKEN,
+        useFactory: (container: Container) => {
+          const embeddingService = container.resolve(EMBEDDING_SERVICE_TOKEN);
+          const vectorStore = container.resolve(VECTOR_STORE_TOKEN);
+          return new RagService(resolvedOptions, embeddingService as never, vectorStore as never);
+        },
+      },
+      RagService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, RagModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      imports: [
+        ...(existing.imports || []),
+        EmbeddingModule,
+        VectorStoreModule,
+      ],
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        RAG_SERVICE_TOKEN,
+        RagService,
+      ],
+    }, RagModule);
+
+    return RagModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, RagModule);
+  }
+}

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;
+  }
+}