@dangao/bun-server 1.12.0 → 2.0.0

package/dist/vector-store/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './vector-store-module';
+export * from './stores/memory-store';
+export * from './stores/pinecone-store';
+export * from './stores/qdrant-store';
+//# sourceMappingURL=index.d.ts.map

package/dist/vector-store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vector-store/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}

package/dist/vector-store/stores/memory-store.d.ts

@@ -0,0 +1,17 @@
+import type { VectorStore, VectorDocument, VectorSearchResult, VectorSearchOptions } from '../types';
+/**
+ * High-performance in-memory vector store using cosine similarity.
+ * Suitable for development and small to medium datasets (up to ~100K documents).
+ */
+export declare class MemoryVectorStore implements VectorStore {
+    private readonly documents;
+    upsert(document: VectorDocument): Promise<void>;
+    upsertBatch(documents: VectorDocument[]): Promise<void>;
+    get(id: string, collection?: string): Promise<VectorDocument | null>;
+    search(query: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    delete(id: string, collection?: string): Promise<boolean>;
+    deleteCollection(collection: string): Promise<void>;
+    count(collection?: string): Promise<number>;
+    private key;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/vector-store/stores/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../../src/vector-store/stores/memory-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAGrG;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAElD,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAIpE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAoBzF,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzD,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASxD,OAAO,CAAC,GAAG;CAGZ"}

package/dist/vector-store/stores/pinecone-store.d.ts

@@ -0,0 +1,27 @@
+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 declare class PineconeVectorStore implements VectorStore {
+    private readonly apiKey;
+    private readonly host;
+    private readonly namespace;
+    constructor(config: PineconeStoreConfig);
+    upsert(document: VectorDocument): Promise<void>;
+    upsertBatch(documents: VectorDocument[]): Promise<void>;
+    get(id: string): Promise<VectorDocument | null>;
+    search(query: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+    deleteCollection(collection: string): Promise<void>;
+    count(): Promise<number>;
+    private request;
+}
+//# sourceMappingURL=pinecone-store.d.ts.map

package/dist/vector-store/stores/pinecone-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinecone-store.d.ts","sourceRoot":"","sources":["../../../src/vector-store/stores/pinecone-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAErG,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEhB,MAAM,EAAE,mBAAmB;IAMjC,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAiB/C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA+BzF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpC,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;YAUvB,OAAO;CAYtB"}

package/dist/vector-store/stores/qdrant-store.d.ts

@@ -0,0 +1,29 @@
+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 declare class QdrantVectorStore implements VectorStore {
+    private readonly url;
+    private readonly collectionName;
+    private readonly apiKey;
+    constructor(config: QdrantStoreConfig);
+    upsert(document: VectorDocument): Promise<void>;
+    upsertBatch(documents: VectorDocument[]): Promise<void>;
+    get(id: string): Promise<VectorDocument | null>;
+    search(query: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    delete(id: string): Promise<boolean>;
+    deleteCollection(collection: string): Promise<void>;
+    count(): Promise<number>;
+    private toNumericId;
+    private request;
+}
+//# sourceMappingURL=qdrant-store.d.ts.map

package/dist/vector-store/stores/qdrant-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant-store.d.ts","sourceRoot":"","sources":["../../../src/vector-store/stores/qdrant-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAErG,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEzB,MAAM,EAAE,iBAAiB;IAM/B,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAqB/C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAmCzF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWpC,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IASrC,OAAO,CAAC,WAAW;YAKL,OAAO;CAYtB"}

package/dist/vector-store/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare const VECTOR_STORE_TOKEN: unique symbol;
+export declare const VECTOR_STORE_OPTIONS_TOKEN: unique symbol;
+/**
+ * Compute cosine similarity between two vectors
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/vector-store/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/vector-store/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,0CAA0C;IAC1C,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,gCAAgC;IAChC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrE,2DAA2D;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACtF,8BAA8B;IAC9B,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,2CAA2C;IAC3C,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,sBAAsB;IACtB,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,eAAkD,CAAC;AAClF,eAAO,MAAM,0BAA0B,eAAoD,CAAC;AAE5F;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAYjE"}

package/dist/vector-store/vector-store-module.d.ts

@@ -0,0 +1,20 @@
+import { type VectorStoreModuleOptions } from './types';
+export declare class VectorStoreModule {
+    /**
+     * Configure the vector store module.
+     *
+     * @example
+     * ```typescript
+     * // Built-in memory store (default):
+     * VectorStoreModule.forRoot({});
+     *
+     * // Pinecone:
+     * VectorStoreModule.forRoot({
+     *   store: new PineconeVectorStore({ apiKey: '...', host: '...' }),
+     * });
+     * ```
+     */
+    static forRoot(options?: VectorStoreModuleOptions): typeof VectorStoreModule;
+    static reset(): void;
+}
+//# sourceMappingURL=vector-store-module.d.ts.map

package/dist/vector-store/vector-store-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store-module.d.ts","sourceRoot":"","sources":["../../src/vector-store/vector-store-module.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,SAAS,CAAC;AAGjB,qBACa,iBAAiB;IAC5B;;;;;;;;;;;;;OAaG;WACW,OAAO,CAAC,OAAO,GAAE,wBAA6B,GAAG,OAAO,iBAAiB;WAqBzE,KAAK,IAAI,IAAI;CAG5B"}

package/docs/ai.md

@@ -0,0 +1,500 @@
+# AI Modules
+
+**English** | [中文](./zh/ai.md)
+
+`@dangao/bun-server` v2.0.0 introduces **9 official AI modules** providing production-ready infrastructure for building LLM-powered applications.
+
+All providers communicate via Bun's native `fetch()` — no third-party AI SDK dependencies are added to the framework package.
+
+---
+
+## Quick Start — 5-Minute Chat API
+
+```bash
+ollama pull llama3.2  # Free local model
+```
+
+```typescript
+import {
+  Application, Controller, Module, Injectable, Inject,
+  POST, Body, AiModule, AiService, OllamaProvider, AI_SERVICE_TOKEN,
+} from '@dangao/bun-server';
+
+AiModule.forRoot({
+  providers: [{ name: 'ollama', provider: OllamaProvider, config: {}, default: true }],
+});
+
+@Injectable()
+class ChatService {
+  constructor(@Inject(AI_SERVICE_TOKEN) private ai: AiService) {}
+  async chat(msg: string) {
+    return this.ai.complete({ messages: [{ role: 'user', content: msg }] });
+  }
+}
+
+@Controller('/chat')
+class ChatController {
+  constructor(private svc: ChatService) {}
+  @POST('/') async post(@Body() b: { message: string }) { return this.svc.chat(b.message); }
+}
+
+@Module({ imports: [AiModule], controllers: [ChatController], providers: [ChatService] })
+class AppModule {}
+
+const app = new Application({ port: 3000 });
+app.registerModule(AppModule);
+app.listen();
+```
+
+---
+
+## Module Overview
+
+| Module | Token | Purpose |
+|--------|-------|---------|
+| `AiModule` | `AI_SERVICE_TOKEN` | LLM providers + Tool Calling + streaming |
+| `ConversationModule` | `CONVERSATION_SERVICE_TOKEN` | Multi-turn conversation history |
+| `PromptModule` | `PROMPT_SERVICE_TOKEN` | Prompt templates + versioning |
+| `EmbeddingModule` | `EMBEDDING_SERVICE_TOKEN` | Text embedding generation |
+| `VectorStoreModule` | `VECTOR_STORE_TOKEN` | Vector similarity search |
+| `RagModule` | `RAG_SERVICE_TOKEN` | RAG ingest + retrieve pipeline |
+| `McpModule` | `MCP_SERVER_TOKEN` | MCP protocol server |
+| `AiGuardModule` | `AI_GUARD_SERVICE_TOKEN` | Content safety |
+
+---
+
+## AiModule — LLM Unified Access
+
+### Configuration
+
+```typescript
+import { AiModule, OpenAIProvider, AnthropicProvider, OllamaProvider, GoogleProvider } from '@dangao/bun-server';
+
+AiModule.forRoot({
+  providers: [
+    { name: 'openai', provider: OpenAIProvider, config: { apiKey: process.env.OPENAI_API_KEY! }, default: true },
+    { name: 'claude', provider: AnthropicProvider, config: { apiKey: process.env.ANTHROPIC_API_KEY! } },
+    { name: 'ollama', provider: OllamaProvider, config: { baseUrl: 'http://localhost:11434' } },
+    { name: 'gemini', provider: GoogleProvider, config: { apiKey: process.env.GOOGLE_API_KEY! } },
+  ],
+  fallback: true,     // Try next provider on failure
+  timeout: 30000,     // Request timeout in ms
+  tools: {
+    autoDiscover: true,  // Auto-register @AiTool() decorated methods
+    maxIterations: 10,   // Max Tool Calling iterations
+  },
+});
+```
+
+### Usage
+
+```typescript
+@Injectable()
+class ChatService {
+  constructor(@Inject(AI_SERVICE_TOKEN) private ai: AiService) {}
+
+  // Non-streaming
+  async complete(messages: AiMessage[]) {
+    return this.ai.complete({ messages, provider: 'openai' });
+  }
+
+  // Streaming (SSE)
+  stream(messages: AiMessage[]): ReadableStream<Uint8Array> {
+    return this.ai.stream({ messages });
+  }
+
+  // Switch provider
+  async withClaude(messages: AiMessage[]) {
+    return this.ai.complete({ messages, provider: 'claude' });
+  }
+}
+```
+
+### Streaming Responses
+
+```typescript
+@GET('/stream')
+public streamChat(@Query('message') message: string): Response {
+  const stream = this.aiService.stream({
+    messages: [{ role: 'user', content: message }],
+  });
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+  });
+}
+```
+
+Each SSE chunk has the format: `data: {"content":"...","done":false}\n\n`
+
+### Tool Calling with @AiTool()
+
+```typescript
+@Injectable()
+class MyTools {
+  @AiTool({
+    name: 'get_weather',
+    description: 'Get current weather for a city',
+    parameters: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+    },
+  })
+  async getWeather({ city }: { city: string }): Promise<string> {
+    return `Weather in ${city}: 22°C, sunny`;
+  }
+}
+
+// Register tools:
+const registry = container.resolve<ToolRegistry>(AI_TOOL_REGISTRY_TOKEN);
+registry.scanAndRegister(new MyTools());
+
+// Complete with tools (auto-loop):
+const response = await aiService.complete({
+  messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],
+  tools: registry.getDefinitions(),
+});
+```
+
+---
+
+## ConversationModule — Multi-Turn Memory
+
+### Configuration
+
+```typescript
+import { ConversationModule, MemoryConversationStore } from '@dangao/bun-server';
+
+ConversationModule.forRoot({
+  store: new MemoryConversationStore(),   // or RedisConversationStore / DatabaseConversationStore
+  maxMessages: 50,
+  autoTrim: true,
+  summaryThreshold: 40,  // Trigger summarization when > 40 messages
+  summarizer: async (messages) => {
+    // Inject AiService to summarize — avoids circular dependency
+    return await aiService.complete({ messages: [...messages, summaryPrompt] }).then(r => r.content);
+  },
+});
+```
+
+### Usage
+
+```typescript
+@POST('/chat')
+async chat(@Body() body: { message: string; conversationId?: string }) {
+  let convId = body.conversationId;
+  if (!convId) {
+    const conv = await this.conversations.create();
+    convId = conv.id;
+  }
+
+  const history = await this.conversations.getHistory(convId);
+  const response = await this.ai.complete({ messages: [...history, { role: 'user', content: body.message }] });
+
+  await this.conversations.appendMessage(convId, { role: 'user', content: body.message });
+  await this.conversations.appendMessage(convId, { role: 'assistant', content: response.content });
+
+  return { conversationId: convId, reply: response.content };
+}
+```
+
+### Stores
+
+| Store | Use case |
+|-------|----------|
+| `MemoryConversationStore` | Development, single-instance (default) |
+| `RedisConversationStore` | Production, multi-instance |
+| `DatabaseConversationStore` | Durable storage, full history queries |
+
+---
+
+## PromptModule — Prompt Templates
+
+### Configuration
+
+```typescript
+import { PromptModule, InMemoryPromptStore, FilePromptStore } from '@dangao/bun-server';
+
+// In-memory (default):
+PromptModule.forRoot({});
+
+// File-based (loads from .prompts/*.json):
+PromptModule.forRoot({
+  store: new FilePromptStore({ promptsDir: './.prompts' }),
+});
+```
+
+### Usage
+
+```typescript
+// Create template
+await promptService.create({
+  id: 'system-assistant',
+  name: 'System: Assistant',
+  content: 'You are {{role}}, a helpful assistant for {{company}}.',
+});
+
+// Render with variables
+const prompt = await promptService.render('system-assistant', {
+  role: 'data analyst',
+  company: 'Acme Corp',
+});
+// "You are data analyst, a helpful assistant for Acme Corp."
+
+// Update creates a new version
+await promptService.update('system-assistant', { content: 'You are {{role}} at {{company}}.' });
+
+// Retrieve specific version
+const v1 = await promptService.getVersion('system-assistant', 1);
+```
+
+---
+
+## EmbeddingModule + VectorStoreModule
+
+### Configuration
+
+```typescript
+import {
+  EmbeddingModule, OpenAIEmbeddingProvider,
+  VectorStoreModule, MemoryVectorStore,
+} from '@dangao/bun-server';
+
+EmbeddingModule.forRoot({
+  provider: { name: 'openai', provider: OpenAIEmbeddingProvider, config: { apiKey: '...' } },
+  batchSize: 100,
+});
+
+VectorStoreModule.forRoot({
+  store: new MemoryVectorStore(),  // or PineconeVectorStore / QdrantVectorStore
+});
+```
+
+### Usage
+
+```typescript
+// Generate embeddings
+const vector = await embeddingService.embed('Hello world');
+const vectors = await embeddingService.embedBatch(['text 1', 'text 2']);
+
+// Vector store operations
+await vectorStore.upsert({ id: 'doc1', vector, content: 'Hello world', collection: 'docs' });
+const results = await vectorStore.search(queryVector, { topK: 5, collection: 'docs', minScore: 0.7 });
+```
+
+---
+
+## RagModule — RAG Pipeline
+
+### Configuration
+
+```typescript
+import { RagModule } from '@dangao/bun-server';
+
+// Requires EmbeddingModule and VectorStoreModule to be imported first
+RagModule.forRoot({
+  collection: 'my-kb',
+  chunkSize: 512,
+  chunkOverlap: 50,
+  topK: 5,
+  minScore: 0.5,
+});
+```
+
+### Usage
+
+```typescript
+@Injectable()
+class KnowledgeService {
+  constructor(@Inject(RAG_SERVICE_TOKEN) private rag: RagService) {}
+
+  // Ingest documents
+  async ingest() {
+    await this.rag.ingest({ type: 'text', content: 'Bun is a fast JS runtime.' });
+    await this.rag.ingest({ type: 'file', path: './docs/manual.md' });
+    await this.rag.ingest({ type: 'url', url: 'https://bun.sh/docs' });
+  }
+
+  // Retrieve context for a query
+  async answer(question: string) {
+    const context = await this.rag.retrieve(question);
+    // context.formatted = "[1] Bun is...\n\n[2] ..."
+    return context;
+  }
+}
+```
+
+---
+
+## McpModule — Model Context Protocol Server
+
+MCP (Model Context Protocol) enables AI clients (Cursor, Claude Desktop, VS Code Copilot) to call your API methods as tools.
+
+### Configuration
+
+```typescript
+import { McpModule } from '@dangao/bun-server';
+
+McpModule.forRoot({
+  transport: 'sse',
+  path: '/mcp',
+  serverInfo: { name: 'my-api', version: '1.0.0' },
+});
+```
+
+### Define MCP Tools
+
+```typescript
+@Injectable()
+class MyTools {
+  @McpTool({
+    name: 'search_products',
+    description: 'Search for products by keyword',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    },
+  })
+  async searchProducts({ query }: { query: string }) {
+    return this.productService.search(query);
+  }
+}
+
+// Register in a controller:
+@Controller('/mcp')
+class McpController {
+  constructor(
+    @Inject(MCP_SERVER_TOKEN) private server: McpServer,
+    private registry: McpRegistry,
+    private tools: MyTools,
+  ) {
+    this.registry.scan(this.tools);
+  }
+
+  @GET('/') sse(): Response { return this.server.createSseResponse(); }
+  @POST('/') async handle(): Promise<Response> { ... }
+}
+```
+
+---
+
+## AiGuardModule — Content Safety
+
+### Configuration
+
+```typescript
+import { AiGuardModule } from '@dangao/bun-server';
+
+AiGuardModule.forRoot({
+  piiDetection: { redact: true },
+  promptInjection: { sensitivity: 'medium' },  // 'low' | 'medium' | 'high'
+  moderation: {
+    openaiApiKey: process.env.OPENAI_API_KEY,  // Uses OpenAI Moderation API
+    blockCategories: ['hate', 'violence', 'sexual'],
+  },
+});
+```
+
+### Usage
+
+```typescript
+// Manual check
+const result = await guardService.check(userInput);
+if (!result.allowed) throw new HttpException(400, 'Content not allowed');
+const safeInput = result.sanitizedInput; // PII-redacted version
+
+// Or throw automatically:
+const safeInput = await guardService.checkOrThrow(userInput);
+
+// Decorator (marks method-level checking):
+@POST('/chat')
+@AiGuard({ piiDetection: true, promptInjection: true })
+async chat(@Body() body: { message: string }) { ... }
+```
+
+---
+
+## Building AI Applications — Best Practices
+
+### 1. Use Ollama for Local Development
+
+```typescript
+// Development: free, no API costs
+AiModule.forRoot({
+  providers: [
+    { name: 'ollama', provider: OllamaProvider, config: {}, default: true },
+    { name: 'openai', provider: OpenAIProvider, config: { apiKey: env.OPENAI_API_KEY! } },
+  ],
+  fallback: true,
+});
+```
+
+### 2. Cache AI Responses
+
+```typescript
+// Combine with CacheModule to avoid redundant LLM calls
+const cached = await cacheService.getOrSet(
+  `ai:${hash(messages)}`,
+  () => aiService.complete({ messages }),
+  60_000, // 60s TTL
+);
+```
+
+### 3. Track Token Usage and Costs
+
+Every `AiResponse` includes `usage`:
+
+```typescript
+const response = await aiService.complete({ messages });
+console.log(response.usage);
+// { promptTokens: 120, completionTokens: 50, totalTokens: 170, estimatedCostUsd: 0.00043 }
+```
+
+### 4. Streaming Best Practices
+
+```typescript
+// Always set proper SSE headers
+return new Response(aiService.stream({ messages }), {
+  headers: {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+  },
+});
+```
+
+### 5. Always Guard User Input
+
+```typescript
+// Apply AiGuard before processing in production:
+const safeMessage = await guardService.checkOrThrow(userInput);
+```
+
+---
+
+## AI Capability Coverage
+
+| Capability | Official Module |
+|---|---|
+| Multi-LLM providers | `AiModule` |
+| Text embeddings | `EmbeddingModule` |
+| Knowledge base / vector search | `VectorStoreModule` |
+| RAG retrieval pipeline | `RagModule` |
+| Conversation memory | `ConversationModule` |
+| Prompt template management | `PromptModule` |
+| Tool / Function Calling | `AiModule` (ToolRegistry + @AiTool()) |
+| Content safety | `AiGuardModule` |
+| MCP protocol server | `McpModule` |
+| AI workflow orchestration | Demo layer (ai-platform-mvp example) |
+
+---
+
+## Related Resources
+
+- [AI Modules Examples](../examples/05-ai/README.md)
+- [AI Platform MVP Demo](../examples/05-ai/ai-platform-mvp/README.md)
+- [Ollama Documentation](https://ollama.ai)
+- [OpenAI API Reference](https://platform.openai.com/docs)
+- [Anthropic API Reference](https://docs.anthropic.com)
+- [MCP Specification](https://modelcontextprotocol.io)