echo-ai-sdk-ts 2.3.1 → 2.5.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,85 @@ 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 TTSConfig {
+    apiKey: string;
+    model?: string;
+}
+declare class HuggingFaceTTS {
+    private client;
+    private defaultModel;
+    constructor(config: TTSConfig);
+    /**
+     * Converts an AI text response into a spoken audio Blob.
+     * Useful for voice-enabled chatbots or IVR systems.
+     */
+    generateAudio(text: string): Promise<Blob>;
+    /**
+     * Helper syntax for Node.js backends needing buffers instead of Blobs.
+     */
+    generateBuffer(text: string): Promise<Buffer>;
+}
+
+interface ImageGenConfig {
+    apiKey: string;
+    model?: string;
+}
+declare class HuggingFaceImageGen {
+    private client;
+    private defaultModel;
+    constructor(config: ImageGenConfig);
+    /**
+     * Generates an image based on the prompt.
+     * Returns standard image Blob.
+     */
+    generate(prompt: string): Promise<Blob>;
+    /**
+     * Generates a base64 encoded string compatible with markdown or HTML `img src`.
+     */
+    generateBase64(prompt: string): Promise<string>;
+    /**
+     * Exposes this generator as a ToolContext that the AgentExecutor can use dynamically.
+     */
+    asTool(): ToolContext;
+}
+
 interface SupportBotConfig {
     gateway: AIModelGateway;
     companyName: string;
@@ -798,6 +884,10 @@ interface SupportBotConfig {
     greeting?: string;
     systemPrompt?: string;
     maxIterations?: number;
+    enablePIIRedaction?: boolean;
+    experiments?: Experiment[];
+    tts?: TTSConfig;
+    imageGen?: ImageGenConfig;
 }
 type BotMiddleware = (ctx: {
     sessionId: string;
@@ -817,7 +907,12 @@ declare class CustomerSupportBot {
     outcomeTracker: OutcomeTracker;
     sessionStore: SessionStore;
     handoff?: HandoffManager;
+    piiRedactor?: PIIRedactor;
+    experimentManager?: ExperimentManager;
+    ttsEngine?: HuggingFaceTTS;
+    imageGenEngine?: HuggingFaceImageGen;
     greeting: string;
+    private defaultSystemPrompt;
     private middlewares;
     constructor(config: SupportBotConfig);
     /** Register a middleware function to run before every chat turn. */
@@ -826,6 +921,13 @@ declare class CustomerSupportBot {
     trackOutcome(sessionId: string, type: string, valueUsd?: number, metadata?: Record<string, any>): void;
     /** Process a customer message and return the bot's response. */
     chat(sessionId: string, message: string): Promise<string>;
+    /**
+     * Process a customer message and return both text and a spoken audio Buffer using the TTS engine.
+     */
+    chatWithVoice(sessionId: string, message: string): Promise<{
+        text: string;
+        audio?: Buffer;
+    }>;
     /** Start tracking analytics for a new session. */
     initSession(sessionId: string): void;
 }
@@ -933,4 +1035,39 @@ 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 };
+interface EndpointConfig {
+    accountId: string;
+    repository: string;
+    accelerator?: string;
+    instanceSize?: string;
+    instanceType?: string;
+    framework?: "pytorch" | "tensorflow" | "custom";
+}
+/**
+ * Manages Serverless / Dedicated Endpoints on Hugging Face API.
+ * Uses REST API since @huggingface/inference is primarily for making queries.
+ */
+declare class InferenceEndpointManager {
+    private token;
+    private baseUrl;
+    constructor(token: string);
+    private get headers();
+    /**
+     * Programmatically creates a dedicated inference endpoint.
+     */
+    createEndpoint(name: string, config: EndpointConfig): Promise<any>;
+    /**
+     * Retrieves the status of an existing endpoint (e.g. "pending", "running", "paused").
+     */
+    getEndpointStatus(accountId: string, endpointName: string): Promise<string>;
+    /**
+     * Pauses a running endpoint to save costs.
+     */
+    pauseEndpoint(accountId: string, endpointName: string): Promise<void>;
+    /**
+     * Resumes a paused endpoint.
+     */
+    resumeEndpoint(accountId: string, endpointName: string): Promise<void>;
+}
+
+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 EndpointConfig, type EscalationTrigger, type Experiment, ExperimentManager, type ExperimentVariant, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, HuggingFaceImageGen, HuggingFaceTTS, type IdentificationResult, type ImageGenConfig, InMemoryStore, InferenceEndpointManager, 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 TTSConfig, 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,85 @@ 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 TTSConfig {
+    apiKey: string;
+    model?: string;
+}
+declare class HuggingFaceTTS {
+    private client;
+    private defaultModel;
+    constructor(config: TTSConfig);
+    /**
+     * Converts an AI text response into a spoken audio Blob.
+     * Useful for voice-enabled chatbots or IVR systems.
+     */
+    generateAudio(text: string): Promise<Blob>;
+    /**
+     * Helper syntax for Node.js backends needing buffers instead of Blobs.
+     */
+    generateBuffer(text: string): Promise<Buffer>;
+}
+
+interface ImageGenConfig {
+    apiKey: string;
+    model?: string;
+}
+declare class HuggingFaceImageGen {
+    private client;
+    private defaultModel;
+    constructor(config: ImageGenConfig);
+    /**
+     * Generates an image based on the prompt.
+     * Returns standard image Blob.
+     */
+    generate(prompt: string): Promise<Blob>;
+    /**
+     * Generates a base64 encoded string compatible with markdown or HTML `img src`.
+     */
+    generateBase64(prompt: string): Promise<string>;
+    /**
+     * Exposes this generator as a ToolContext that the AgentExecutor can use dynamically.
+     */
+    asTool(): ToolContext;
+}
+
 interface SupportBotConfig {
     gateway: AIModelGateway;
     companyName: string;
@@ -798,6 +884,10 @@ interface SupportBotConfig {
     greeting?: string;
     systemPrompt?: string;
     maxIterations?: number;
+    enablePIIRedaction?: boolean;
+    experiments?: Experiment[];
+    tts?: TTSConfig;
+    imageGen?: ImageGenConfig;
 }
 type BotMiddleware = (ctx: {
     sessionId: string;
@@ -817,7 +907,12 @@ declare class CustomerSupportBot {
     outcomeTracker: OutcomeTracker;
     sessionStore: SessionStore;
     handoff?: HandoffManager;
+    piiRedactor?: PIIRedactor;
+    experimentManager?: ExperimentManager;
+    ttsEngine?: HuggingFaceTTS;
+    imageGenEngine?: HuggingFaceImageGen;
     greeting: string;
+    private defaultSystemPrompt;
     private middlewares;
     constructor(config: SupportBotConfig);
     /** Register a middleware function to run before every chat turn. */
@@ -826,6 +921,13 @@ declare class CustomerSupportBot {
     trackOutcome(sessionId: string, type: string, valueUsd?: number, metadata?: Record<string, any>): void;
     /** Process a customer message and return the bot's response. */
     chat(sessionId: string, message: string): Promise<string>;
+    /**
+     * Process a customer message and return both text and a spoken audio Buffer using the TTS engine.
+     */
+    chatWithVoice(sessionId: string, message: string): Promise<{
+        text: string;
+        audio?: Buffer;
+    }>;
     /** Start tracking analytics for a new session. */
     initSession(sessionId: string): void;
 }
@@ -933,4 +1035,39 @@ 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 };
+interface EndpointConfig {
+    accountId: string;
+    repository: string;
+    accelerator?: string;
+    instanceSize?: string;
+    instanceType?: string;
+    framework?: "pytorch" | "tensorflow" | "custom";
+}
+/**
+ * Manages Serverless / Dedicated Endpoints on Hugging Face API.
+ * Uses REST API since @huggingface/inference is primarily for making queries.
+ */
+declare class InferenceEndpointManager {
+    private token;
+    private baseUrl;
+    constructor(token: string);
+    private get headers();
+    /**
+     * Programmatically creates a dedicated inference endpoint.
+     */
+    createEndpoint(name: string, config: EndpointConfig): Promise<any>;
+    /**
+     * Retrieves the status of an existing endpoint (e.g. "pending", "running", "paused").
+     */
+    getEndpointStatus(accountId: string, endpointName: string): Promise<string>;
+    /**
+     * Pauses a running endpoint to save costs.
+     */
+    pauseEndpoint(accountId: string, endpointName: string): Promise<void>;
+    /**
+     * Resumes a paused endpoint.
+     */
+    resumeEndpoint(accountId: string, endpointName: string): Promise<void>;
+}
+
+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 EndpointConfig, type EscalationTrigger, type Experiment, ExperimentManager, type ExperimentVariant, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, HuggingFaceImageGen, HuggingFaceTTS, type IdentificationResult, type ImageGenConfig, InMemoryStore, InferenceEndpointManager, 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 TTSConfig, 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 };