echo-ai-sdk-ts 2.2.0

package/dist/index.d.ts

@@ -0,0 +1,806 @@
+import { z } from 'zod';
+
+declare const ChatMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<["user", "assistant", "system", "tool"]>;
+    content: z.ZodString;
+    tool_calls: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    tool_call_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: Record<string, any>[] | undefined;
+    tool_call_id?: string | undefined;
+}, {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: Record<string, any>[] | undefined;
+    tool_call_id?: string | undefined;
+}>;
+type ChatMessage = z.infer<typeof ChatMessageSchema>;
+declare const ChatRequestSchema: z.ZodObject<{
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["user", "assistant", "system", "tool"]>;
+        content: z.ZodString;
+        tool_calls: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+        tool_call_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        tool_calls?: Record<string, any>[] | undefined;
+        tool_call_id?: string | undefined;
+    }, {
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        tool_calls?: Record<string, any>[] | undefined;
+        tool_call_id?: string | undefined;
+    }>, "many">;
+    tools: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    model_family: z.ZodDefault<z.ZodEnum<["fast", "smart", "capable"]>>;
+    temperature: z.ZodDefault<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    stream: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    messages: {
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        tool_calls?: Record<string, any>[] | undefined;
+        tool_call_id?: string | undefined;
+    }[];
+    model_family: "fast" | "smart" | "capable";
+    temperature: number;
+    stream: boolean;
+    tools?: Record<string, any>[] | undefined;
+    max_tokens?: number | undefined;
+}, {
+    messages: {
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+        tool_calls?: Record<string, any>[] | undefined;
+        tool_call_id?: string | undefined;
+    }[];
+    tools?: Record<string, any>[] | undefined;
+    model_family?: "fast" | "smart" | "capable" | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    stream?: boolean | undefined;
+}>;
+type ChatRequest = z.infer<typeof ChatRequestSchema>;
+declare const UsageMetricsSchema: z.ZodObject<{
+    prompt_tokens: z.ZodDefault<z.ZodNumber>;
+    completion_tokens: z.ZodDefault<z.ZodNumber>;
+    total_tokens: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}, {
+    prompt_tokens?: number | undefined;
+    completion_tokens?: number | undefined;
+    total_tokens?: number | undefined;
+}>;
+type UsageMetrics = z.infer<typeof UsageMetricsSchema>;
+declare const ChatResponseSchema: z.ZodObject<{
+    content: z.ZodNullable<z.ZodString>;
+    tool_calls: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>>;
+    usage: z.ZodObject<{
+        prompt_tokens: z.ZodDefault<z.ZodNumber>;
+        completion_tokens: z.ZodDefault<z.ZodNumber>;
+        total_tokens: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    }, {
+        prompt_tokens?: number | undefined;
+        completion_tokens?: number | undefined;
+        total_tokens?: number | undefined;
+    }>;
+    provider_name: z.ZodString;
+    model_name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string | null;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    provider_name: string;
+    model_name: string;
+    tool_calls?: Record<string, any>[] | null | undefined;
+}, {
+    content: string | null;
+    usage: {
+        prompt_tokens?: number | undefined;
+        completion_tokens?: number | undefined;
+        total_tokens?: number | undefined;
+    };
+    provider_name: string;
+    model_name: string;
+    tool_calls?: Record<string, any>[] | null | undefined;
+}>;
+type ChatResponse = z.infer<typeof ChatResponseSchema>;
+
+declare abstract class BaseProvider {
+    /** The unique identifier of the provider (e.g., 'openai', 'anthropic'). */
+    abstract get providerName(): string;
+    /**
+     * Translates a universal ChatRequest into the provider-specific payload,
+     * executes the request, and formats it back to a standard ChatResponse.
+     */
+    abstract chatComplete(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Same as chatComplete but yields text chunks asynchronously.
+     */
+    abstract chatStream(request: ChatRequest): AsyncGenerator<string, void, unknown>;
+}
+
+/**
+ * Middleware interface for the AI Model Gateway.
+ * Intercept, transform, or log requests/responses flowing through the gateway.
+ */
+interface GatewayMiddleware {
+    /** Called before a request is sent to any provider. Can modify the request. */
+    onRequest?: (request: ChatRequest) => ChatRequest | Promise<ChatRequest>;
+    /** Called after a successful response is received. Can modify the response. */
+    onResponse?: (response: ChatResponse, request: ChatRequest) => ChatResponse | Promise<ChatResponse>;
+    /** Called when a provider throws an error. */
+    onError?: (error: Error, providerName: string) => void;
+}
+/**
+ * Applies a middleware pipeline to requests and responses.
+ */
+declare function applyRequestMiddleware(middlewares: GatewayMiddleware[], request: ChatRequest): Promise<ChatRequest>;
+declare function applyResponseMiddleware(middlewares: GatewayMiddleware[], response: ChatResponse, request: ChatRequest): Promise<ChatResponse>;
+
+declare class AIModelGateway {
+    providers: BaseProvider[];
+    private middlewares;
+    constructor(providers: BaseProvider[]);
+    /**
+     * Register middleware to intercept, transform, or log requests/responses.
+     * Middleware is executed in registration order.
+     */
+    use(middleware: GatewayMiddleware): this;
+    chatComplete(request: ChatRequest): Promise<ChatResponse>;
+    chatStream(request: ChatRequest): AsyncGenerator<string, void, unknown>;
+}
+
+interface BaseMemoryStore {
+    getMessages(sessionId: string): Promise<ChatMessage[]>;
+    addMessage(sessionId: string, message: ChatMessage): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+}
+declare class InMemoryStore implements BaseMemoryStore {
+    maxHistory: number;
+    private memory;
+    constructor(maxHistory?: number);
+    getMessages(sessionId: string): Promise<ChatMessage[]>;
+    addMessage(sessionId: string, message: ChatMessage): Promise<void>;
+    clearSession(sessionId: string): Promise<void>;
+    /** Returns the number of active sessions in memory. */
+    get sessionCount(): number;
+}
+
+interface ToolContext<T = any> {
+    name: string;
+    description: string;
+    schema: z.ZodType<T>;
+    execute: (args: T) => Promise<string | any>;
+    getMcpSchema: () => any;
+}
+/**
+ * Factory function to create strongly-typed tools utilizing Zod.
+ * Automatically handles conversion to JSONSchema.
+ */
+declare function createTool<T>(options: {
+    name: string;
+    description: string;
+    schema: z.ZodType<T>;
+    execute: (args: T) => Promise<string | any>;
+}): ToolContext<T>;
+
+declare class ChatAgent {
+    private _executor;
+    constructor(gateway: AIModelGateway, memory?: BaseMemoryStore);
+    chat(sessionId: string, userInput: string): Promise<string>;
+}
+declare class ToolAgent {
+    private _executor;
+    constructor(gateway: AIModelGateway, tools: ToolContext[], memory?: BaseMemoryStore);
+    run(sessionId: string, userInput: string, maxIterations?: number): Promise<string>;
+}
+
+declare class EchoAI {
+    gateway: AIModelGateway;
+    constructor(options?: {
+        providers?: BaseProvider[];
+    });
+    createChatAgent(): ChatAgent;
+    createToolAgent(tools: ToolContext[]): ToolAgent;
+}
+
+interface AgentTelemetry {
+    onAgentStart?: (sessionId: string, input: string) => void;
+    onAgentIteration?: (sessionId: string, iteration: number) => void;
+    onToolStart?: (sessionId: string, toolName: string, args: any) => void;
+    onToolEnd?: (sessionId: string, toolName: string, result: string) => void;
+    onTokenUsage?: (sessionId: string, provider: string, model: string, usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    }) => void;
+    onAgentEnd?: (sessionId: string, output: string) => void;
+}
+
+declare class AgentExecutor {
+    private gateway;
+    private memory;
+    private tools;
+    private systemPrompt?;
+    private telemetry?;
+    constructor(options: {
+        gateway: AIModelGateway | BaseProvider;
+        memory: BaseMemoryStore;
+        tools?: ToolContext[];
+        systemPrompt?: string;
+        telemetry?: AgentTelemetry;
+    });
+    execute(sessionId: string, userInput: string, maxIterations?: number): Promise<string>;
+    /**
+     * Forces the LLM to output strictly structured JSON validated against the provided Zod schema.
+     * Throws StructuredOutputError if the output cannot be parsed.
+     */
+    executeStructured<T>(sessionId: string, userInput: string, schema: z.ZodType<T>, maxIterations?: number): Promise<T>;
+}
+
+/**
+ * Chains multiple agents sequentially.
+ * The output of one agent becomes the input of the next.
+ * Perfect for pipelines like: Summarize → Translate → Format.
+ */
+declare class AgentPipeline {
+    private agents;
+    addStage(label: string, executor: AgentExecutor): this;
+    run(sessionId: string, initialInput: string): Promise<string>;
+}
+/**
+ * Routes user input to the most appropriate agent based on intent classification.
+ * Useful for building multi-skill assistants (e.g., support bot vs. sales bot).
+ */
+declare class AgentRouter {
+    private routes;
+    private fallback?;
+    addRoute(label: string, pattern: RegExp, executor: AgentExecutor): this;
+    setFallback(executor: AgentExecutor): this;
+    route(sessionId: string, userInput: string): Promise<string>;
+}
+
+declare const calculatorTool: ToolContext<{
+    expression: string;
+}>;
+declare const dateTimeTool: ToolContext<{}>;
+declare const webSearchTool: ToolContext<{
+    query: string;
+}>;
+
+/**
+ * Wraps an AIModelGateway with a TTL-based in-memory response cache.
+ * Identical requests within the TTL window are served instantly from cache,
+ * eliminating redundant API calls and saving tokens.
+ */
+declare class CachedGateway {
+    private gateway;
+    private ttlMs;
+    private cache;
+    constructor(gateway: AIModelGateway, ttlMs?: number);
+    private getCacheKey;
+    chatComplete(request: ChatRequest): Promise<ChatResponse>;
+    /** Streaming is not cacheable, passthrough directly. */
+    chatStream(request: ChatRequest): AsyncGenerator<string, void, unknown>;
+    clearCache(): void;
+}
+
+declare class PromptVersionError extends Error {
+    constructor(message: string);
+}
+declare class PromptTemplate {
+    name: string;
+    version: string;
+    template: string;
+    requiredVars: Set<string>;
+    major: number;
+    minor: number;
+    patch: number;
+    constructor(options: {
+        name: string;
+        version: string;
+        template: string;
+        requiredVars?: string[];
+    });
+    /**
+     * Injects variables into the template string.
+     * Uses `{{variableName}}` mustache-style placeholders.
+     */
+    render(variables: Record<string, any>): string;
+}
+/**
+ * Central repository for managing prompt templates and their versions.
+ * Allows decoupling prompt engineering from application code releases.
+ * Supports instant rollbacks and A/B testing.
+ */
+declare class PromptRegistry {
+    private registry;
+    private activeVersions;
+    register(template: PromptTemplate, isActive?: boolean): void;
+    getTemplate(name: string, version?: string): PromptTemplate;
+    setActiveVersion(name: string, version: string): void;
+    listVersions(name: string): string[];
+}
+
+/**
+ * Thrown when all providers in the Gateway exhaust their retry attempts.
+ */
+declare class GatewayRoutingError extends Error {
+    errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Thrown when a required peer dependency (e.g., openai or @anthropic-ai/sdk) is not installed.
+ */
+declare class ProviderDependencyError extends Error {
+    constructor(providerName: string);
+}
+/**
+ * Thrown when a tool fails during execution within the Agent loop.
+ */
+declare class ToolExecutionError extends Error {
+    toolName: string;
+    constructor(toolName: string, message: string);
+}
+/**
+ * Thrown when no providers are configured in the EchoAI client.
+ */
+declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when input validation fails on any public API method.
+ */
+declare class ValidationError extends Error {
+    constructor(method: string, message: string);
+}
+/**
+ * Thrown when the AgentExecutor exceeds its maximum iteration limit.
+ */
+declare class AgentIterationLimitError extends Error {
+    iterations: number;
+    constructor(iterations: number);
+}
+/**
+ * Thrown when structured output parsing fails.
+ */
+declare class StructuredOutputError extends Error {
+    rawOutput: string;
+    constructor(rawOutput: string, parseError: string);
+}
+
+interface TranscriptionResult {
+    text: string;
+    language?: string;
+    duration?: number;
+    segments?: TranscriptionSegment[];
+}
+interface TranscriptionSegment {
+    start: number;
+    end: number;
+    text: string;
+    confidence?: number;
+}
+interface STTOptions {
+    language?: string;
+    prompt?: string;
+    temperature?: number;
+    timestamps?: boolean;
+}
+/**
+ * Abstract base class for Speech-to-Text providers.
+ * Extend this to integrate any STT engine (Whisper, Deepgram, AssemblyAI, etc.)
+ */
+declare abstract class BaseSTTProvider {
+    abstract get providerName(): string;
+    abstract transcribe(audio: Buffer, options?: STTOptions): Promise<TranscriptionResult>;
+}
+
+type TTSVoice = "alloy" | "echo" | "fable" | "onyx" | "nova" | "shimmer" | string;
+type TTSFormat = "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm";
+interface TTSOptions {
+    voice?: TTSVoice;
+    speed?: number;
+    format?: TTSFormat;
+    model?: string;
+}
+interface TTSResult {
+    audio: Buffer;
+    format: TTSFormat;
+    durationMs?: number;
+}
+/**
+ * Abstract base class for Text-to-Speech providers.
+ * Extend this to integrate any TTS engine (OpenAI, ElevenLabs, Google, etc.)
+ */
+declare abstract class BaseTTSProvider {
+    abstract get providerName(): string;
+    abstract synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
+}
+
+interface SpeakerProfile {
+    id: string;
+    name: string;
+    embedding: number[];
+    enrolledAt: Date;
+}
+interface IdentificationResult {
+    speakerId: string;
+    speakerName: string;
+    confidence: number;
+    matched: boolean;
+}
+interface VerificationResult {
+    verified: boolean;
+    confidence: number;
+}
+/**
+ * Abstract base class for Speaker Recognition providers.
+ * Extend this to integrate speaker verification engines (Azure, custom models, etc.)
+ */
+declare abstract class BaseSpeakerRecognizer {
+    abstract get providerName(): string;
+    abstract extractEmbedding(audio: Buffer): Promise<number[]>;
+}
+/**
+ * In-memory voiceprint store for speaker enrollment and identification.
+ * Uses cosine similarity for matching voice embeddings.
+ */
+declare class VoiceprintStore {
+    private profiles;
+    threshold: number;
+    constructor(threshold?: number);
+    enroll(id: string, name: string, embedding: number[]): SpeakerProfile;
+    identify(embedding: number[]): IdentificationResult;
+    verify(speakerId: string, embedding: number[]): VerificationResult;
+    getProfile(id: string): SpeakerProfile | undefined;
+    listSpeakers(): SpeakerProfile[];
+    removeSpeaker(id: string): boolean;
+    private cosineSimilarity;
+}
+
+declare class OpenAIWhisperSTT extends BaseSTTProvider {
+    private client;
+    constructor(apiKey: string);
+    get providerName(): string;
+    transcribe(audio: Buffer, options?: STTOptions): Promise<TranscriptionResult>;
+}
+
+declare class OpenAITTS extends BaseTTSProvider {
+    private client;
+    constructor(apiKey: string);
+    get providerName(): string;
+    synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
+}
+
+/**
+ * Unified voice client providing one-liner access to STT, TTS, and Speaker Recognition.
+ * Auto-configures OpenAI providers from environment variables.
+ */
+declare class EchoVoice {
+    stt: BaseSTTProvider;
+    tts: BaseTTSProvider;
+    speakers: VoiceprintStore;
+    private recognizer?;
+    constructor(options?: {
+        stt?: BaseSTTProvider;
+        tts?: BaseTTSProvider;
+        recognizer?: BaseSpeakerRecognizer;
+        speakerThreshold?: number;
+    });
+    /** Transcribe audio to text. */
+    transcribe(audio: Buffer, options?: STTOptions): Promise<TranscriptionResult>;
+    /** Convert text to audio. Returns a raw Buffer of the audio file. */
+    speak(text: string, options?: TTSOptions): Promise<TTSResult>;
+    /**
+     * Enroll a speaker by providing their audio sample.
+     * Requires a BaseSpeakerRecognizer to extract embeddings.
+     */
+    enrollSpeaker(id: string, name: string, audio: Buffer): Promise<void>;
+    /**
+     * Identify who is speaking from an audio sample.
+     * Returns the best matching speaker profile.
+     */
+    identifySpeaker(audio: Buffer): Promise<IdentificationResult>;
+    /**
+     * Verify if an audio sample belongs to a specific enrolled speaker.
+     */
+    verifySpeaker(speakerId: string, audio: Buffer): Promise<VerificationResult>;
+}
+
+interface APIConnectorConfig {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    authToken?: string;
+    timeout?: number;
+}
+interface FetchResult {
+    status: number;
+    data: any;
+    ok: boolean;
+}
+/**
+ * Connects the chatbot to your website's API to fetch live data.
+ * The bot can query your endpoints to answer customer questions with real data.
+ */
+declare class APIConnector {
+    private baseUrl;
+    private headers;
+    private timeout;
+    constructor(config: APIConnectorConfig);
+    get(endpoint: string): Promise<FetchResult>;
+    post(endpoint: string, body: any): Promise<FetchResult>;
+    private request;
+}
+
+interface VectorEntry {
+    id: string;
+    content: string;
+    vector: number[];
+    metadata?: Record<string, any>;
+}
+interface SearchResult {
+    content: string;
+    score: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Enhanced in-memory vector store with persistence and similarity thresholding.
+ */
+declare class MemoryVectorStore {
+    private entries;
+    /** Add a single vector entry. */
+    add(entry: VectorEntry): Promise<void>;
+    /** Add multiple vector entries at once. */
+    addBatch(entries: VectorEntry[]): Promise<void>;
+    /** Retrieve top K results above a minimum similarity score. */
+    search(queryVector: number[], k?: number, minScore?: number): Promise<SearchResult[]>;
+    /** Save the entire store to a JSON file. */
+    saveToFile(path: string): Promise<void>;
+    /** Load store entries from a JSON file. */
+    loadFromFile(path: string): Promise<void>;
+    /** Clear all stored vectors. */
+    clear(): void;
+    get size(): number;
+}
+interface ChunkOptions {
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+declare function chunkText(text: string, options?: ChunkOptions): string[];
+interface KnowledgeBaseConfig {
+    openaiApiKey: string;
+    embeddingModel?: string;
+    chunkSize?: number;
+    chunkOverlap?: number;
+    topK?: number;
+    minScore?: number;
+}
+declare class KnowledgeBase {
+    private store;
+    private openai;
+    private embeddingModel;
+    private chunkOpts;
+    private topK;
+    private minScore;
+    private docCounter;
+    constructor(config: KnowledgeBaseConfig);
+    ingestText(text: string, source?: string): Promise<number>;
+    ingestURL(url: string): Promise<number>;
+    query(question: string, topK?: number): Promise<string>;
+    save(path: string): Promise<void>;
+    load(path: string): Promise<void>;
+    private embed;
+    private embedBatch;
+}
+
+/**
+ * Enterprise Conversation Analytics Engine.
+ * Tracks resolution rates, CSAT, response latency, token costs, and top queries.
+ */
+interface ConversationRecord {
+    sessionId: string;
+    startTime: number;
+    endTime?: number;
+    messageCount: number;
+    resolved: boolean;
+    handedOff: boolean;
+    csatScore?: number;
+    totalTokens: number;
+    totalCostUsd: number;
+    topQueries: string[];
+    responseTimes: number[];
+    model?: string;
+}
+interface AnalyticsSnapshot {
+    totalConversations: number;
+    resolvedCount: number;
+    resolutionRate: number;
+    handoffRate: number;
+    avgCsatScore: number;
+    avgResponseTimeMs: number;
+    totalTokensUsed: number;
+    totalCostUsd: number;
+    avgTokensPerConversation: number;
+    avgCostPerConversation: number;
+    topQueries: {
+        query: string;
+        count: number;
+    }[];
+    conversationsPerHour: number;
+}
+declare const OPENAI_PRICING: Record<string, {
+    input: number;
+    output: number;
+}>;
+declare class ConversationAnalytics {
+    private records;
+    private queryFrequency;
+    estimateTokens(text: string): number;
+    calculateCost(model: string, tokens: number, type?: "input" | "output"): number;
+    startConversation(sessionId: string, model?: string): void;
+    recordQuery(sessionId: string, query: string): void;
+    recordResponse(sessionId: string, reply: string, latencyMs: number): void;
+    markResolved(sessionId: string): void;
+    markHandedOff(sessionId: string): void;
+    recordCSAT(sessionId: string, score: number): void;
+    getSnapshot(): AnalyticsSnapshot;
+    private emptySnapshot;
+    exportJSON(): string;
+    importJSON(json: string): void;
+    reset(): void;
+}
+
+/**
+ * Advanced Human Handoff Manager.
+ * Detects escalation triggers (frustration, sentiment, max turns)
+ * and dispatches to external helpdesks via webhooks with HMAC security.
+ */
+type EscalationTrigger = "explicit_request" | "low_confidence" | "frustration" | "sentiment" | "max_turns" | "keyword";
+interface HandoffEvent {
+    sessionId: string;
+    trigger: EscalationTrigger;
+    conversationHistory: {
+        role: string;
+        content: string;
+    }[];
+    customerMessage: string;
+    summary?: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+interface HandoffConfig {
+    webhookUrl?: string;
+    webhookSecret?: string;
+    maxTurnsBeforeHandoff?: number;
+    negativeSentimentThreshold?: number;
+    frustrationKeywords?: string[];
+    explicitKeywords?: string[];
+    onHandoff?: (event: HandoffEvent) => void | Promise<void>;
+    offlineMessage?: string;
+}
+declare class HandoffManager {
+    private webhookUrl?;
+    private webhookSecret?;
+    private maxTurns;
+    private sentimentThreshold;
+    private frustrationKeywords;
+    private explicitKeywords;
+    private onHandoff?;
+    offlineMessage: string;
+    private turnCounts;
+    private negativeStrikes;
+    constructor(config: HandoffConfig);
+    /** Detect negative sentiment in a message (simple rule-based). */
+    private isNegative;
+    /** Check if a message should trigger handoff. Returns the trigger type or null. */
+    shouldEscalate(sessionId: string, message: string): EscalationTrigger | null;
+    /** Execute the handoff: fire webhook, invoke callback, return user message. */
+    escalate(sessionId: string, trigger: EscalationTrigger, conversationHistory: {
+        role: string;
+        content: string;
+    }[], customerMessage: string, summary?: string, metadata?: Record<string, any>): Promise<string>;
+    private dispatchWebhook;
+}
+
+interface SupportBotConfig {
+    gateway: AIModelGateway;
+    companyName: string;
+    companyDescription?: string;
+    apiConnector?: APIConnectorConfig;
+    knowledgeBase?: KnowledgeBaseConfig;
+    handoff?: HandoffConfig;
+    memory?: BaseMemoryStore;
+    telemetry?: AgentTelemetry;
+    customTools?: ToolContext[];
+    greeting?: string;
+    systemPrompt?: string;
+    maxIterations?: number;
+}
+type BotMiddleware = (ctx: {
+    sessionId: string;
+    message: string;
+    bot: CustomerSupportBot;
+}) => Promise<void | string>;
+/**
+ * Pre-configured customer support chatbot agent.
+ * Connects to your website API, answers questions, uses a RAG knowledge base,
+ * tracks analytics, and handles human handoffs.
+ */
+declare class CustomerSupportBot {
+    private executor;
+    private connector?;
+    knowledgeBase?: KnowledgeBase;
+    analytics: ConversationAnalytics;
+    handoff?: HandoffManager;
+    greeting: string;
+    private middlewares;
+    constructor(config: SupportBotConfig);
+    /** Register a middleware function to run before every chat turn. */
+    use(middleware: BotMiddleware): void;
+    /** Process a customer message and return the bot's response. */
+    chat(sessionId: string, message: string): Promise<string>;
+    /** Start tracking analytics for a new session. */
+    initSession(sessionId: string): void;
+}
+
+interface ChatWidgetTheme {
+    primaryColor?: string;
+    headerBg?: string;
+    headerText?: string;
+    bubbleBg?: string;
+    userBubbleBg?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+    position?: "bottom-right" | "bottom-left";
+    width?: string;
+    height?: string;
+}
+interface ChatWidgetConfig {
+    serverEndpoint: string;
+    title?: string;
+    subtitle?: string;
+    greeting?: string;
+    placeholder?: string;
+    theme?: ChatWidgetTheme;
+    enableVoice?: boolean;
+}
+/**
+ * Generates a self-contained, embeddable HTML/CSS/JS chatbot widget.
+ * Paste the output into any website — zero dependencies required client-side.
+ */
+declare class ChatWidget {
+    static generate(config: ChatWidgetConfig): string;
+}
+
+interface ServerConfig extends SupportBotConfig {
+    port?: number;
+    corsOrigins?: string | string[];
+}
+/**
+ * Creates a complete Express-compatible request handler for the chatbot.
+ * Handles /chat, /analytics, /handoff, and /knowledge ingestion.
+ */
+declare function createChatHandler(bot: CustomerSupportBot): (req: any, res: any) => Promise<any>;
+/**
+ * Quick-start: Spins up a minimal Express server with the chatbot endpoints.
+ * Requires `express` and `cors` to be installed in the consumer's project.
+ */
+declare function startChatServer(config: ServerConfig): Promise<void>;
+
+export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, 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, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, 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 };