echo-ai-sdk-ts 2.3.1 → 2.4.0

package/README.md

@@ -113,6 +113,41 @@ bot.use(async ({ sessionId, message }) => {
 });
 ```
 
+
+### 🚀 Tier 2 Pro-Grade Features
+
+#### 🌐 Omnichannel Sync
+Connect your bot to Slack and Telegram while maintaining a single user context.
+```typescript
+import { TelegramAdapter, SlackAdapter } from "echo-ai-sdk";
+
+const tg = new TelegramAdapter({ bot, token: "TG_TOKEN" });
+await tg.start();
+
+const slack = new SlackAdapter({ bot, signingSecret: "...", token: "..." });
+await slack.start();
+```
+
+#### 💾 Persistent Session Store
+Move beyond memory. Use `FileSessionStore` for local persistence or implement `SessionStore` for Redis.
+```typescript
+import { FileSessionStore } from "echo-ai-sdk";
+const bot = new CustomerSupportBot({
+  sessionStore: new FileSessionStore("./sessions"),
+});
+```
+
+#### 📈 Outcome-Based Billing & ROI
+Track the *real value* of your AI by recording business outcomes.
+```typescript
+// Inside a tool or middleware
+bot.trackOutcome(sessionId, "lead_captured", 50.0);
+
+const stats = bot.analytics.getSnapshot();
+console.log(`ROI: ${stats.roi * 100}%`);
+console.log(`Value Generated: $${stats.totalValueGeneratedUsd}`);
+```
+
 ---
 
 ## Installation

package/dist/index.d.mts

@@ -655,6 +655,7 @@ interface ConversationRecord {
     topQueries: string[];
     responseTimes: number[];
     model?: string;
+    variantId?: string;
 }
 interface AnalyticsSnapshot {
     totalConversations: number;
@@ -667,6 +668,12 @@ interface AnalyticsSnapshot {
     totalCostUsd: number;
     totalValueGeneratedUsd: number;
     roi: number;
+    variants?: Record<string, {
+        totalConversations: number;
+        totalValueGeneratedUsd: number;
+        resolutionRate: number;
+        roi: number;
+    }>;
     avgTokensPerConversation: number;
     avgCostPerConversation: number;
     topQueries: {
@@ -686,7 +693,7 @@ declare class ConversationAnalytics {
     constructor(outcomeTracker?: OutcomeTracker);
     estimateTokens(text: string): number;
     calculateCost(model: string, tokens: number, type?: "input" | "output"): number;
-    startConversation(sessionId: string, model?: string): void;
+    startConversation(sessionId: string, model?: string, variantId?: string): void;
     recordQuery(sessionId: string, query: string): void;
     recordResponse(sessionId: string, reply: string, latencyMs: number): void;
     markResolved(sessionId: string): void;
@@ -784,6 +791,43 @@ declare class FileSessionStore implements SessionStore {
     clear(): Promise<void>;
 }
 
+interface RedactionRule {
+    name: string;
+    pattern: RegExp;
+    placeholder: string;
+}
+declare const DEFAULT_REDACTION_RULES: RedactionRule[];
+declare class PIIRedactor {
+    private rules;
+    constructor(rules?: RedactionRule[]);
+    /** Scans text and replaces any matched patterns with their placeholders. */
+    redact(text: string): string;
+    /** Adds custom redaction rules to the engine. */
+    addRule(rule: RedactionRule): void;
+}
+
+interface ExperimentVariant {
+    id: string;
+    weight: number;
+    config: Record<string, any>;
+}
+interface Experiment {
+    name: string;
+    variants: ExperimentVariant[];
+}
+declare class ExperimentManager {
+    private experiments;
+    constructor(experiments?: Experiment[]);
+    registerExperiment(exp: Experiment): void;
+    /**
+     * Assigns a user to a specific variant based on deterministic hashing of their sessionId.
+     * This guarantees 'sticky sessions' where the same user always gets the same A/B test variant.
+     */
+    assignVariant(experimentName: string, sessionId: string): string | null;
+    /** Retrieves the variant config object for an assigned variant id. */
+    getVariantConfig(experimentName: string, variantId: string): Record<string, any> | null;
+}
+
 interface SupportBotConfig {
     gateway: AIModelGateway;
     companyName: string;
@@ -798,6 +842,8 @@ interface SupportBotConfig {
     greeting?: string;
     systemPrompt?: string;
     maxIterations?: number;
+    enablePIIRedaction?: boolean;
+    experiments?: Experiment[];
 }
 type BotMiddleware = (ctx: {
     sessionId: string;
@@ -817,7 +863,10 @@ declare class CustomerSupportBot {
     outcomeTracker: OutcomeTracker;
     sessionStore: SessionStore;
     handoff?: HandoffManager;
+    piiRedactor?: PIIRedactor;
+    experimentManager?: ExperimentManager;
     greeting: string;
+    private defaultSystemPrompt;
     private middlewares;
     constructor(config: SupportBotConfig);
     /** Register a middleware function to run before every chat turn. */
@@ -933,4 +982,4 @@ declare class TelegramAdapter extends ChannelAdapter {
     private sendMessage;
 }
 
-export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChannelAdapter, type ChannelConfig, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, EchoAI, EchoVoice, type EscalationTrigger, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemorySessionStore, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, type OutcomeRecord, OutcomeTracker, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SessionStore, SlackAdapter, type SlackConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, TelegramAdapter, type TelegramConfig, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };
+export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChannelAdapter, type ChannelConfig, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, DEFAULT_REDACTION_RULES, EchoAI, EchoVoice, type EscalationTrigger, type Experiment, ExperimentManager, type ExperimentVariant, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemorySessionStore, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, type OutcomeRecord, OutcomeTracker, PIIRedactor, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type RedactionRule, type STTOptions, type SearchResult, type ServerConfig, type SessionStore, SlackAdapter, type SlackConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, TelegramAdapter, type TelegramConfig, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };

package/dist/index.d.ts

@@ -655,6 +655,7 @@ interface ConversationRecord {
     topQueries: string[];
     responseTimes: number[];
     model?: string;
+    variantId?: string;
 }
 interface AnalyticsSnapshot {
     totalConversations: number;
@@ -667,6 +668,12 @@ interface AnalyticsSnapshot {
     totalCostUsd: number;
     totalValueGeneratedUsd: number;
     roi: number;
+    variants?: Record<string, {
+        totalConversations: number;
+        totalValueGeneratedUsd: number;
+        resolutionRate: number;
+        roi: number;
+    }>;
     avgTokensPerConversation: number;
     avgCostPerConversation: number;
     topQueries: {
@@ -686,7 +693,7 @@ declare class ConversationAnalytics {
     constructor(outcomeTracker?: OutcomeTracker);
     estimateTokens(text: string): number;
     calculateCost(model: string, tokens: number, type?: "input" | "output"): number;
-    startConversation(sessionId: string, model?: string): void;
+    startConversation(sessionId: string, model?: string, variantId?: string): void;
     recordQuery(sessionId: string, query: string): void;
     recordResponse(sessionId: string, reply: string, latencyMs: number): void;
     markResolved(sessionId: string): void;
@@ -784,6 +791,43 @@ declare class FileSessionStore implements SessionStore {
     clear(): Promise<void>;
 }
 
+interface RedactionRule {
+    name: string;
+    pattern: RegExp;
+    placeholder: string;
+}
+declare const DEFAULT_REDACTION_RULES: RedactionRule[];
+declare class PIIRedactor {
+    private rules;
+    constructor(rules?: RedactionRule[]);
+    /** Scans text and replaces any matched patterns with their placeholders. */
+    redact(text: string): string;
+    /** Adds custom redaction rules to the engine. */
+    addRule(rule: RedactionRule): void;
+}
+
+interface ExperimentVariant {
+    id: string;
+    weight: number;
+    config: Record<string, any>;
+}
+interface Experiment {
+    name: string;
+    variants: ExperimentVariant[];
+}
+declare class ExperimentManager {
+    private experiments;
+    constructor(experiments?: Experiment[]);
+    registerExperiment(exp: Experiment): void;
+    /**
+     * Assigns a user to a specific variant based on deterministic hashing of their sessionId.
+     * This guarantees 'sticky sessions' where the same user always gets the same A/B test variant.
+     */
+    assignVariant(experimentName: string, sessionId: string): string | null;
+    /** Retrieves the variant config object for an assigned variant id. */
+    getVariantConfig(experimentName: string, variantId: string): Record<string, any> | null;
+}
+
 interface SupportBotConfig {
     gateway: AIModelGateway;
     companyName: string;
@@ -798,6 +842,8 @@ interface SupportBotConfig {
     greeting?: string;
     systemPrompt?: string;
     maxIterations?: number;
+    enablePIIRedaction?: boolean;
+    experiments?: Experiment[];
 }
 type BotMiddleware = (ctx: {
     sessionId: string;
@@ -817,7 +863,10 @@ declare class CustomerSupportBot {
     outcomeTracker: OutcomeTracker;
     sessionStore: SessionStore;
     handoff?: HandoffManager;
+    piiRedactor?: PIIRedactor;
+    experimentManager?: ExperimentManager;
     greeting: string;
+    private defaultSystemPrompt;
     private middlewares;
     constructor(config: SupportBotConfig);
     /** Register a middleware function to run before every chat turn. */
@@ -933,4 +982,4 @@ declare class TelegramAdapter extends ChannelAdapter {
     private sendMessage;
 }
 
-export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChannelAdapter, type ChannelConfig, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, EchoAI, EchoVoice, type EscalationTrigger, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemorySessionStore, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, type OutcomeRecord, OutcomeTracker, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SessionStore, SlackAdapter, type SlackConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, TelegramAdapter, type TelegramConfig, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };
+export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChannelAdapter, type ChannelConfig, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, DEFAULT_REDACTION_RULES, EchoAI, EchoVoice, type EscalationTrigger, type Experiment, ExperimentManager, type ExperimentVariant, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemorySessionStore, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, type OutcomeRecord, OutcomeTracker, PIIRedactor, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type RedactionRule, type STTOptions, type SearchResult, type ServerConfig, type SessionStore, SlackAdapter, type SlackConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, TelegramAdapter, type TelegramConfig, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };

package/dist/index.js

@@ -9503,8 +9503,10 @@ __export(index_exports, {
   ConfigurationError: () => ConfigurationError,
   ConversationAnalytics: () => ConversationAnalytics,
   CustomerSupportBot: () => CustomerSupportBot,
+  DEFAULT_REDACTION_RULES: () => DEFAULT_REDACTION_RULES,
   EchoAI: () => EchoAI,
   EchoVoice: () => EchoVoice,
+  ExperimentManager: () => ExperimentManager,
   FileSessionStore: () => FileSessionStore,
   GatewayRoutingError: () => GatewayRoutingError,
   HandoffManager: () => HandoffManager,
@@ -9516,6 +9518,7 @@ __export(index_exports, {
   OpenAITTS: () => OpenAITTS,
   OpenAIWhisperSTT: () => OpenAIWhisperSTT,
   OutcomeTracker: () => OutcomeTracker,
+  PIIRedactor: () => PIIRedactor,
   PromptRegistry: () => PromptRegistry,
   PromptTemplate: () => PromptTemplate,
   PromptVersionError: () => PromptVersionError,
@@ -15559,7 +15562,7 @@ var ConversationAnalytics = class {
     const rate = type === "input" ? pricing.input : pricing.output;
     return tokens / 1e6 * rate;
   }
-  startConversation(sessionId, model = "gpt-4o-mini") {
+  startConversation(sessionId, model = "gpt-4o-mini", variantId) {
     if (!this.records.has(sessionId)) {
       this.records.set(sessionId, {
         sessionId,
@@ -15571,7 +15574,8 @@ var ConversationAnalytics = class {
         totalCostUsd: 0,
         topQueries: [],
         responseTimes: [],
-        model
+        model,
+        variantId
       });
     }
   }
@@ -15636,6 +15640,31 @@ var ConversationAnalytics = class {
     const firstConvo = all.length > 0 ? Math.min(...all.map((r2) => r2.startTime)) : now;
     const hourSpan = Math.max(1, (now - firstConvo) / 36e5);
     const topQueries = [...this.queryFrequency.entries()].sort((a2, b2) => b2[1] - a2[1]).slice(0, 20).map(([query, count]) => ({ query, count }));
+    const variants = {};
+    const groupedByVariant = all.reduce((acc, r2) => {
+      const v2 = r2.variantId || "default";
+      if (!acc[v2]) acc[v2] = [];
+      acc[v2].push(r2);
+      return acc;
+    }, {});
+    for (const [variantId, vRecords] of Object.entries(groupedByVariant)) {
+      const vTotal = vRecords.length;
+      const vResolved = vRecords.filter((r2) => r2.resolved).length;
+      let vValue = 0;
+      if (this.outcomeTracker) {
+        vRecords.forEach((r2) => {
+          const outRecords = this.outcomeTracker.outcomes?.get(r2.sessionId) || [];
+          vValue += outRecords.reduce((s2, o2) => s2 + o2.valueUsd, 0);
+        });
+      }
+      const vCost = vRecords.reduce((s2, r2) => s2 + r2.totalCostUsd, 0);
+      variants[variantId] = {
+        totalConversations: vTotal,
+        totalValueGeneratedUsd: vValue,
+        resolutionRate: vTotal > 0 ? vResolved / vTotal : 0,
+        roi: vCost > 0 ? (vValue - vCost) / vCost : 0
+      };
+    }
     return {
       totalConversations: total,
       resolvedCount: resolved,
@@ -15905,6 +15934,93 @@ var OutcomeTracker = class {
   }
 };
 
+// src/analytics/redact.ts
+var DEFAULT_REDACTION_RULES = [
+  {
+    name: "email",
+    pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+    placeholder: "[REDACTED_EMAIL]"
+  },
+  {
+    name: "phone",
+    pattern: /\b(?:\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    placeholder: "[REDACTED_PHONE]"
+  },
+  {
+    name: "credit_card",
+    // Standard 16 digit match with optional dashes or spaces
+    pattern: /\b(?:\d[ -]*?){13,16}\b/g,
+    placeholder: "[REDACTED_CC]"
+  },
+  {
+    name: "ssn",
+    // Standard US SSN
+    pattern: /\b\d{3}[-.\s]?\d{2}[-.\s]?\d{4}\b/g,
+    placeholder: "[REDACTED_SSN]"
+  }
+];
+var PIIRedactor = class {
+  rules;
+  constructor(rules) {
+    this.rules = rules || DEFAULT_REDACTION_RULES;
+  }
+  /** Scans text and replaces any matched patterns with their placeholders. */
+  redact(text) {
+    if (!text) return text;
+    let redacted = text;
+    for (const rule of this.rules) {
+      redacted = redacted.replace(rule.pattern, rule.placeholder);
+    }
+    return redacted;
+  }
+  /** Adds custom redaction rules to the engine. */
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+};
+
+// src/analytics/experiment.ts
+var crypto2 = __toESM(require("crypto"));
+var ExperimentManager = class {
+  experiments = /* @__PURE__ */ new Map();
+  constructor(experiments) {
+    if (experiments) {
+      experiments.forEach((e2) => this.registerExperiment(e2));
+    }
+  }
+  registerExperiment(exp) {
+    this.experiments.set(exp.name, exp);
+  }
+  /**
+   * Assigns a user to a specific variant based on deterministic hashing of their sessionId.
+   * This guarantees 'sticky sessions' where the same user always gets the same A/B test variant.
+   */
+  assignVariant(experimentName, sessionId) {
+    const exp = this.experiments.get(experimentName);
+    if (!exp || exp.variants.length === 0) return null;
+    if (exp.variants.length === 1) return exp.variants[0].id;
+    const totalWeight = exp.variants.reduce((sum, v2) => sum + v2.weight, 0);
+    const hash = crypto2.createHash("md5").update(`${experimentName}_${sessionId}`).digest("hex");
+    const hashInt = parseInt(hash.slice(0, 8), 16);
+    const bucket = hashInt % totalWeight;
+    let cumulative = 0;
+    for (const variant of exp.variants) {
+      cumulative += variant.weight;
+      if (bucket < cumulative) {
+        return variant.id;
+      }
+    }
+    return exp.variants[0].id;
+  }
+  /** Retrieves the variant config object for an assigned variant id. */
+  getVariantConfig(experimentName, variantId) {
+    const exp = this.experiments.get(experimentName);
+    if (!exp) return null;
+    const v2 = exp.variants.find((v3) => v3.id === variantId);
+    return v2 ? v2.config : null;
+  }
+};
+
 // src/widget/bot.ts
 var CustomerSupportBot = class {
   executor;
@@ -15914,7 +16030,10 @@ var CustomerSupportBot = class {
   outcomeTracker;
   sessionStore;
   handoff;
+  piiRedactor;
+  experimentManager;
   greeting;
+  defaultSystemPrompt;
   middlewares = [];
   constructor(config) {
     this.outcomeTracker = new OutcomeTracker();
@@ -15926,6 +16045,12 @@ var CustomerSupportBot = class {
     if (config.handoff) {
       this.handoff = new HandoffManager(config.handoff);
     }
+    if (config.enablePIIRedaction) {
+      this.piiRedactor = new PIIRedactor();
+    }
+    if (config.experiments && config.experiments.length > 0) {
+      this.experimentManager = new ExperimentManager(config.experiments);
+    }
     const tools = [];
     if (config.apiConnector) {
       this.connector = new APIConnector(config.apiConnector);
@@ -15957,11 +16082,12 @@ Your role:
 - If you can't find an answer, politely suggest contacting human support
 - Always maintain a warm, professional tone
 - Never make up data \u2014 always verify through the API or context when available`;
+    this.defaultSystemPrompt = config.systemPrompt || defaultSystemPrompt;
     this.executor = new AgentExecutor({
       gateway: config.gateway,
       memory: config.memory || new InMemoryStore(100),
       tools,
-      systemPrompt: config.systemPrompt || defaultSystemPrompt,
+      systemPrompt: this.defaultSystemPrompt,
       telemetry: config.telemetry
     });
     this.greeting = config.greeting || `Hello! \u{1F44B} Welcome to ${config.companyName}. How can I help you today?`;
@@ -15976,15 +16102,28 @@ Your role:
   }
   /** Process a customer message and return the bot's response. */
   async chat(sessionId, message) {
-    this.analytics.startConversation(sessionId);
-    this.analytics.recordQuery(sessionId, message);
+    const activeMessage = this.piiRedactor ? this.piiRedactor.redact(message) : message;
+    let variantId;
+    if (this.experimentManager) {
+      variantId = this.experimentManager.assignVariant("default_experiment", sessionId) || void 0;
+      if (variantId) {
+        const config = this.experimentManager.getVariantConfig("default_experiment", variantId);
+        if (config && config.systemPrompt) {
+          this.executor.systemPrompt = config.systemPrompt;
+        } else {
+          this.executor.systemPrompt = this.defaultSystemPrompt;
+        }
+      }
+    }
+    this.analytics.startConversation(sessionId, "gpt-4o-mini", variantId);
+    this.analytics.recordQuery(sessionId, activeMessage);
     const startTime = Date.now();
     for (const mw of this.middlewares) {
-      const result2 = await mw({ sessionId, message, bot: this });
+      const result2 = await mw({ sessionId, message: activeMessage, bot: this });
       if (typeof result2 === "string") return result2;
     }
     if (this.handoff) {
-      const trigger = this.handoff.shouldEscalate(sessionId, message);
+      const trigger = this.handoff.shouldEscalate(sessionId, activeMessage);
       if (trigger) {
         const history = await this.executor.memory.getMessages(sessionId);
         let summary = "Customer needs assistance.";
@@ -15992,23 +16131,23 @@ Your role:
           summary = await this.executor.gateway.chat([
             { role: "system", content: "Summarize the customer's problem in one concise sentence for a human support agent context." },
             ...history,
-            { role: "user", content: message }
+            { role: "user", content: activeMessage }
           ]);
         } catch {
         }
-        const reply = await this.handoff.escalate(sessionId, trigger, history, message, summary);
+        const reply = await this.handoff.escalate(sessionId, trigger, history, activeMessage, summary);
         this.analytics.markHandedOff(sessionId);
         return reply;
       }
     }
-    let enhancedMessage = message;
+    let enhancedMessage = activeMessage;
     if (this.knowledgeBase) {
-      const context = await this.knowledgeBase.query(message);
+      const context = await this.knowledgeBase.query(activeMessage);
       if (context) {
         enhancedMessage = `Context from Knowledge Base:
 ${context}
 
-User Question: ${message}`;
+User Question: ${activeMessage}`;
       }
     }
     try {
@@ -16019,7 +16158,7 @@ User Question: ${message}`;
       return reply;
     } catch (e2) {
       if (this.handoff) {
-        return this.handoff.escalate(sessionId, "low_confidence", [], message, `Error: ${e2.message}`);
+        return this.handoff.escalate(sessionId, "low_confidence", [], activeMessage, `Error: ${e2.message}`);
       }
       throw e2;
     }
@@ -16326,8 +16465,10 @@ var TelegramAdapter = class extends ChannelAdapter {
   ConfigurationError,
   ConversationAnalytics,
   CustomerSupportBot,
+  DEFAULT_REDACTION_RULES,
   EchoAI,
   EchoVoice,
+  ExperimentManager,
   FileSessionStore,
   GatewayRoutingError,
   HandoffManager,
@@ -16339,6 +16480,7 @@ var TelegramAdapter = class extends ChannelAdapter {
   OpenAITTS,
   OpenAIWhisperSTT,
   OutcomeTracker,
+  PIIRedactor,
   PromptRegistry,
   PromptTemplate,
   PromptVersionError,

package/dist/index.mjs

@@ -13270,7 +13270,7 @@ var ConversationAnalytics = class {
     const rate = type === "input" ? pricing.input : pricing.output;
     return tokens / 1e6 * rate;
   }
-  startConversation(sessionId, model = "gpt-4o-mini") {
+  startConversation(sessionId, model = "gpt-4o-mini", variantId) {
     if (!this.records.has(sessionId)) {
       this.records.set(sessionId, {
         sessionId,
@@ -13282,7 +13282,8 @@ var ConversationAnalytics = class {
         totalCostUsd: 0,
         topQueries: [],
         responseTimes: [],
-        model
+        model,
+        variantId
       });
     }
   }
@@ -13347,6 +13348,31 @@ var ConversationAnalytics = class {
     const firstConvo = all.length > 0 ? Math.min(...all.map((r) => r.startTime)) : now;
     const hourSpan = Math.max(1, (now - firstConvo) / 36e5);
     const topQueries = [...this.queryFrequency.entries()].sort((a, b) => b[1] - a[1]).slice(0, 20).map(([query, count]) => ({ query, count }));
+    const variants = {};
+    const groupedByVariant = all.reduce((acc, r) => {
+      const v = r.variantId || "default";
+      if (!acc[v]) acc[v] = [];
+      acc[v].push(r);
+      return acc;
+    }, {});
+    for (const [variantId, vRecords] of Object.entries(groupedByVariant)) {
+      const vTotal = vRecords.length;
+      const vResolved = vRecords.filter((r) => r.resolved).length;
+      let vValue = 0;
+      if (this.outcomeTracker) {
+        vRecords.forEach((r) => {
+          const outRecords = this.outcomeTracker.outcomes?.get(r.sessionId) || [];
+          vValue += outRecords.reduce((s, o) => s + o.valueUsd, 0);
+        });
+      }
+      const vCost = vRecords.reduce((s, r) => s + r.totalCostUsd, 0);
+      variants[variantId] = {
+        totalConversations: vTotal,
+        totalValueGeneratedUsd: vValue,
+        resolutionRate: vTotal > 0 ? vResolved / vTotal : 0,
+        roi: vCost > 0 ? (vValue - vCost) / vCost : 0
+      };
+    }
     return {
       totalConversations: total,
       resolvedCount: resolved,
@@ -13616,6 +13642,93 @@ var OutcomeTracker = class {
   }
 };
 
+// src/analytics/redact.ts
+var DEFAULT_REDACTION_RULES = [
+  {
+    name: "email",
+    pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+    placeholder: "[REDACTED_EMAIL]"
+  },
+  {
+    name: "phone",
+    pattern: /\b(?:\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    placeholder: "[REDACTED_PHONE]"
+  },
+  {
+    name: "credit_card",
+    // Standard 16 digit match with optional dashes or spaces
+    pattern: /\b(?:\d[ -]*?){13,16}\b/g,
+    placeholder: "[REDACTED_CC]"
+  },
+  {
+    name: "ssn",
+    // Standard US SSN
+    pattern: /\b\d{3}[-.\s]?\d{2}[-.\s]?\d{4}\b/g,
+    placeholder: "[REDACTED_SSN]"
+  }
+];
+var PIIRedactor = class {
+  rules;
+  constructor(rules) {
+    this.rules = rules || DEFAULT_REDACTION_RULES;
+  }
+  /** Scans text and replaces any matched patterns with their placeholders. */
+  redact(text) {
+    if (!text) return text;
+    let redacted = text;
+    for (const rule of this.rules) {
+      redacted = redacted.replace(rule.pattern, rule.placeholder);
+    }
+    return redacted;
+  }
+  /** Adds custom redaction rules to the engine. */
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+};
+
+// src/analytics/experiment.ts
+import * as crypto2 from "crypto";
+var ExperimentManager = class {
+  experiments = /* @__PURE__ */ new Map();
+  constructor(experiments) {
+    if (experiments) {
+      experiments.forEach((e) => this.registerExperiment(e));
+    }
+  }
+  registerExperiment(exp) {
+    this.experiments.set(exp.name, exp);
+  }
+  /**
+   * Assigns a user to a specific variant based on deterministic hashing of their sessionId.
+   * This guarantees 'sticky sessions' where the same user always gets the same A/B test variant.
+   */
+  assignVariant(experimentName, sessionId) {
+    const exp = this.experiments.get(experimentName);
+    if (!exp || exp.variants.length === 0) return null;
+    if (exp.variants.length === 1) return exp.variants[0].id;
+    const totalWeight = exp.variants.reduce((sum, v) => sum + v.weight, 0);
+    const hash = crypto2.createHash("md5").update(`${experimentName}_${sessionId}`).digest("hex");
+    const hashInt = parseInt(hash.slice(0, 8), 16);
+    const bucket = hashInt % totalWeight;
+    let cumulative = 0;
+    for (const variant of exp.variants) {
+      cumulative += variant.weight;
+      if (bucket < cumulative) {
+        return variant.id;
+      }
+    }
+    return exp.variants[0].id;
+  }
+  /** Retrieves the variant config object for an assigned variant id. */
+  getVariantConfig(experimentName, variantId) {
+    const exp = this.experiments.get(experimentName);
+    if (!exp) return null;
+    const v = exp.variants.find((v2) => v2.id === variantId);
+    return v ? v.config : null;
+  }
+};
+
 // src/widget/bot.ts
 var CustomerSupportBot = class {
   executor;
@@ -13625,7 +13738,10 @@ var CustomerSupportBot = class {
   outcomeTracker;
   sessionStore;
   handoff;
+  piiRedactor;
+  experimentManager;
   greeting;
+  defaultSystemPrompt;
   middlewares = [];
   constructor(config) {
     this.outcomeTracker = new OutcomeTracker();
@@ -13637,6 +13753,12 @@ var CustomerSupportBot = class {
     if (config.handoff) {
       this.handoff = new HandoffManager(config.handoff);
     }
+    if (config.enablePIIRedaction) {
+      this.piiRedactor = new PIIRedactor();
+    }
+    if (config.experiments && config.experiments.length > 0) {
+      this.experimentManager = new ExperimentManager(config.experiments);
+    }
     const tools = [];
     if (config.apiConnector) {
       this.connector = new APIConnector(config.apiConnector);
@@ -13668,11 +13790,12 @@ Your role:
 - If you can't find an answer, politely suggest contacting human support
 - Always maintain a warm, professional tone
 - Never make up data \u2014 always verify through the API or context when available`;
+    this.defaultSystemPrompt = config.systemPrompt || defaultSystemPrompt;
     this.executor = new AgentExecutor({
       gateway: config.gateway,
       memory: config.memory || new InMemoryStore(100),
       tools,
-      systemPrompt: config.systemPrompt || defaultSystemPrompt,
+      systemPrompt: this.defaultSystemPrompt,
       telemetry: config.telemetry
     });
     this.greeting = config.greeting || `Hello! \u{1F44B} Welcome to ${config.companyName}. How can I help you today?`;
@@ -13687,15 +13810,28 @@ Your role:
   }
   /** Process a customer message and return the bot's response. */
   async chat(sessionId, message) {
-    this.analytics.startConversation(sessionId);
-    this.analytics.recordQuery(sessionId, message);
+    const activeMessage = this.piiRedactor ? this.piiRedactor.redact(message) : message;
+    let variantId;
+    if (this.experimentManager) {
+      variantId = this.experimentManager.assignVariant("default_experiment", sessionId) || void 0;
+      if (variantId) {
+        const config = this.experimentManager.getVariantConfig("default_experiment", variantId);
+        if (config && config.systemPrompt) {
+          this.executor.systemPrompt = config.systemPrompt;
+        } else {
+          this.executor.systemPrompt = this.defaultSystemPrompt;
+        }
+      }
+    }
+    this.analytics.startConversation(sessionId, "gpt-4o-mini", variantId);
+    this.analytics.recordQuery(sessionId, activeMessage);
     const startTime = Date.now();
     for (const mw of this.middlewares) {
-      const result2 = await mw({ sessionId, message, bot: this });
+      const result2 = await mw({ sessionId, message: activeMessage, bot: this });
       if (typeof result2 === "string") return result2;
     }
     if (this.handoff) {
-      const trigger = this.handoff.shouldEscalate(sessionId, message);
+      const trigger = this.handoff.shouldEscalate(sessionId, activeMessage);
       if (trigger) {
         const history = await this.executor.memory.getMessages(sessionId);
         let summary = "Customer needs assistance.";
@@ -13703,23 +13839,23 @@ Your role:
           summary = await this.executor.gateway.chat([
             { role: "system", content: "Summarize the customer's problem in one concise sentence for a human support agent context." },
             ...history,
-            { role: "user", content: message }
+            { role: "user", content: activeMessage }
           ]);
         } catch {
         }
-        const reply = await this.handoff.escalate(sessionId, trigger, history, message, summary);
+        const reply = await this.handoff.escalate(sessionId, trigger, history, activeMessage, summary);
         this.analytics.markHandedOff(sessionId);
         return reply;
       }
     }
-    let enhancedMessage = message;
+    let enhancedMessage = activeMessage;
     if (this.knowledgeBase) {
-      const context = await this.knowledgeBase.query(message);
+      const context = await this.knowledgeBase.query(activeMessage);
       if (context) {
         enhancedMessage = `Context from Knowledge Base:
 ${context}
 
-User Question: ${message}`;
+User Question: ${activeMessage}`;
       }
     }
     try {
@@ -13730,7 +13866,7 @@ User Question: ${message}`;
       return reply;
     } catch (e) {
       if (this.handoff) {
-        return this.handoff.escalate(sessionId, "low_confidence", [], message, `Error: ${e.message}`);
+        return this.handoff.escalate(sessionId, "low_confidence", [], activeMessage, `Error: ${e.message}`);
       }
       throw e;
     }
@@ -14036,8 +14172,10 @@ export {
   ConfigurationError,
   ConversationAnalytics,
   CustomerSupportBot,
+  DEFAULT_REDACTION_RULES,
   EchoAI,
   EchoVoice,
+  ExperimentManager,
   FileSessionStore,
   GatewayRoutingError,
   HandoffManager,
@@ -14049,6 +14187,7 @@ export {
   OpenAITTS,
   OpenAIWhisperSTT,
   OutcomeTracker,
+  PIIRedactor,
   PromptRegistry,
   PromptTemplate,
   PromptVersionError,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "echo-ai-sdk-ts",
-  "version": "2.3.1",
-  "description": "Echo AI SDK: Tier 2 Pro-Grade (Omnichannel, Outcome Billing, Session Persistence)",
+  "version": "2.4.0",
+  "description": "Echo AI SDK: Tier 3 Enterprise Premium (PII Redaction, A/B Testing, Omnichannel, RAG)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",