@thinkhive/sdk 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,629 @@
+/**
+ * ThinkHive TypeScript SDK
+ * OpenTelemetry-based observability for AI agents with Explainer integration
+ *
+ * @version 2.0.0
+ */
+export interface InitOptions {
+    /** ThinkHive API key (starts with th_) */
+    apiKey?: string;
+    /** Agent ID for legacy authentication */
+    agentId?: string;
+    /** ThinkHive API endpoint */
+    endpoint?: string;
+    /** Service name for traces */
+    serviceName?: string;
+    /** Enable auto-instrumentation */
+    autoInstrument?: boolean;
+    /** Frameworks to auto-instrument */
+    frameworks?: Array<'langchain' | 'openai' | 'anthropic' | 'llamaindex'>;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export interface TraceOptions {
+    /** User's message/query */
+    userMessage: string;
+    /** Agent's response */
+    agentResponse: string;
+    /** User's detected intent */
+    userIntent?: string;
+    /** Outcome: success, failure, partial_success */
+    outcome?: 'success' | 'failure' | 'partial_success';
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Session ID for conversation tracking */
+    sessionId?: string;
+    /** Conversation history */
+    conversationHistory?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Span data for detailed analysis */
+    spans?: SpanData[];
+    /** Business context for ROI calculation */
+    businessContext?: BusinessContext;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface SpanData {
+    id?: string;
+    name: string;
+    type: 'llm' | 'tool' | 'retrieval' | 'embedding' | 'chain' | 'custom';
+    startTime?: Date;
+    endTime?: Date;
+    durationMs?: number;
+    status?: 'ok' | 'error' | 'timeout';
+    error?: string;
+    input?: unknown;
+    output?: unknown;
+    model?: string;
+    provider?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    toolName?: string;
+    toolParameters?: Record<string, unknown>;
+    query?: string;
+    documentCount?: number;
+    topScore?: number;
+    sources?: string[];
+    children?: SpanData[];
+}
+export interface BusinessContext {
+    /** Customer ID */
+    customerId?: string;
+    /** Transaction value in dollars */
+    transactionValue?: number;
+    /** Priority level */
+    priority?: 'low' | 'medium' | 'high' | 'critical';
+    /** Department */
+    department?: string;
+    /** Industry vertical */
+    industry?: string;
+    /** Custom fields */
+    custom?: Record<string, unknown>;
+}
+export interface ExplainabilityResult {
+    traceId: string;
+    explainabilityId: string;
+    summary: string;
+    outcome: {
+        verdict: 'success' | 'partial_success' | 'failure';
+        confidence: number;
+        reasoning: string;
+    };
+    businessImpact: {
+        impactScore: number;
+        customerSatisfaction: number;
+        revenueRisk: string;
+    };
+    recommendations: Array<{
+        priority: string;
+        category: string;
+        action: string;
+        expectedImpact: string;
+    }>;
+    ragEvaluation?: {
+        groundedness: number;
+        faithfulness: number;
+        answerRelevance: number;
+    };
+    hallucinationReport?: {
+        detected: boolean;
+        types: string[];
+        severity: string;
+    };
+    processingTimeMs: number;
+}
+export interface AnalyzeOptions {
+    /** Force a specific analysis tier */
+    tier?: 'rule_based' | 'fast_llm' | 'full_llm' | 'deep';
+    /** Include RAG evaluation */
+    includeRagEvaluation?: boolean;
+    /** Include hallucination detection */
+    includeHallucinationCheck?: boolean;
+    /** Wait for analysis to complete (sync mode) */
+    waitForResult?: boolean;
+    /** Webhook URL for async notification */
+    webhookUrl?: string;
+}
+export interface FeedbackOptions {
+    /** Trace ID to provide feedback for */
+    traceId: string;
+    /** User rating (1-5) */
+    rating?: number;
+    /** Was the response helpful */
+    wasHelpful?: boolean;
+    /** Specific issues encountered */
+    issues?: Array<'slow_response' | 'incorrect' | 'unhelpful' | 'hallucination' | 'off_topic' | 'other'>;
+    /** Free-form comment */
+    comment?: string;
+}
+/**
+ * Initialize ThinkHive SDK
+ *
+ * @example
+ * ```typescript
+ * import { init } from '@thinkhive/sdk';
+ *
+ * init({
+ *   apiKey: 'th_your_api_key',
+ *   serviceName: 'my-ai-agent',
+ *   autoInstrument: true,
+ *   frameworks: ['langchain', 'openai'],
+ * });
+ * ```
+ */
+export declare function init(options?: InitOptions): void;
+/**
+ * Get the global tracer
+ */
+export declare function getTracer(): import("@opentelemetry/api").Tracer;
+/**
+ * Check if SDK is initialized
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Trace an LLM call
+ *
+ * @example
+ * ```typescript
+ * const response = await traceLLM({
+ *   name: 'chat_completion',
+ *   modelName: 'gpt-4',
+ *   provider: 'openai',
+ * }, async () => {
+ *   return await openai.chat.completions.create({ ... });
+ * });
+ * ```
+ */
+export declare function traceLLM<T>(options: {
+    name: string;
+    modelName?: string;
+    provider?: string;
+    input?: unknown;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Trace a retrieval operation
+ *
+ * @example
+ * ```typescript
+ * const docs = await traceRetrieval({
+ *   name: 'vector_search',
+ *   query: 'What is the return policy?',
+ * }, async () => {
+ *   return await vectorStore.similaritySearch(query, 5);
+ * });
+ * ```
+ */
+export declare function traceRetrieval<T>(options: {
+    name: string;
+    query?: string;
+    topK?: number;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Trace a tool call
+ *
+ * @example
+ * ```typescript
+ * const result = await traceTool({
+ *   name: 'search_orders',
+ *   toolName: 'OrderLookup',
+ *   parameters: { orderId: '12345' },
+ * }, async () => {
+ *   return await orderService.lookup('12345');
+ * });
+ * ```
+ */
+export declare function traceTool<T>(options: {
+    name: string;
+    toolName?: string;
+    parameters?: Record<string, unknown>;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Trace a chain/workflow
+ *
+ * @example
+ * ```typescript
+ * const result = await traceChain({
+ *   name: 'customer_support_chain',
+ * }, async () => {
+ *   // Multiple LLM calls, tools, etc.
+ * });
+ * ```
+ */
+export declare function traceChain<T>(options: {
+    name: string;
+    input?: unknown;
+}, fn: () => Promise<T>): Promise<T>;
+/**
+ * Explainer API client for trace analysis
+ */
+export declare const explainer: {
+    /**
+     * Analyze a trace and get explainability insights
+     *
+     * @example
+     * ```typescript
+     * const result = await explainer.analyze({
+     *   userMessage: 'Help me with my order #12345',
+     *   agentResponse: 'I found your order...',
+     *   outcome: 'success',
+     *   spans: [
+     *     { name: 'order_lookup', type: 'tool', durationMs: 150 },
+     *     { name: 'gpt-4', type: 'llm', durationMs: 2500, model: 'gpt-4' },
+     *   ],
+     * });
+     * ```
+     */
+    analyze(trace: TraceOptions, options?: AnalyzeOptions): Promise<ExplainabilityResult>;
+    /**
+     * Batch analyze multiple traces
+     *
+     * @example
+     * ```typescript
+     * const results = await explainer.analyzeBatch([
+     *   { userMessage: 'Q1', agentResponse: 'A1' },
+     *   { userMessage: 'Q2', agentResponse: 'A2' },
+     * ]);
+     * ```
+     */
+    analyzeBatch(traces: TraceOptions[], options?: AnalyzeOptions): Promise<{
+        results: ExplainabilityResult[];
+        summary: {
+            total: number;
+            successCount: number;
+            failureCount: number;
+            averageProcessingTime: number;
+        };
+    }>;
+    /**
+     * Get a previously analyzed trace
+     */
+    get(traceId: string): Promise<ExplainabilityResult>;
+    /**
+     * Search traces semantically
+     *
+     * @example
+     * ```typescript
+     * const results = await explainer.search({
+     *   query: 'order refund issues',
+     *   filters: { outcome: 'failure' },
+     *   limit: 10,
+     * });
+     * ```
+     */
+    search(params: {
+        query: string;
+        filters?: {
+            outcome?: "success" | "failure" | "partial_success";
+            minImpactScore?: number;
+            dateRange?: {
+                from: Date;
+                to: Date;
+            };
+        };
+        limit?: number;
+    }): Promise<{
+        results: Array<ExplainabilityResult & {
+            similarity: number;
+        }>;
+        total: number;
+    }>;
+};
+/**
+ * Feedback API for improving analysis quality
+ */
+export declare const feedback: {
+    /**
+     * Submit feedback for a trace
+     *
+     * @example
+     * ```typescript
+     * await feedback.submit({
+     *   traceId: 'trace_123',
+     *   rating: 5,
+     *   wasHelpful: true,
+     * });
+     * ```
+     */
+    submit(options: FeedbackOptions): Promise<{
+        success: boolean;
+    }>;
+};
+/**
+ * Quality metrics API for RAG evaluation and hallucination detection
+ */
+export declare const quality: {
+    /**
+     * Get RAG evaluation scores for a trace
+     */
+    getRagScores(traceId: string): Promise<{
+        contextRelevance: number;
+        contextPrecision: number;
+        contextRecall: number;
+        groundedness: number;
+        faithfulness: number;
+        answerRelevance: number;
+        citationAccuracy: number;
+        citationCompleteness: number;
+        overallGrade: string;
+    }>;
+    /**
+     * Get hallucination report for a trace
+     */
+    getHallucinationReport(traceId: string): Promise<{
+        hasHallucinations: boolean;
+        severity: "none" | "low" | "medium" | "high";
+        confidence: number;
+        detectedTypes: Array<{
+            type: string;
+            description: string;
+            evidence: string;
+            severity: string;
+        }>;
+    }>;
+    /**
+     * Evaluate RAG quality for custom input
+     */
+    evaluateRag(input: {
+        query: string;
+        response: string;
+        contexts: Array<{
+            content: string;
+            source?: string;
+            score?: number;
+        }>;
+    }): Promise<{
+        scores: Record<string, number>;
+        grade: string;
+        groundedSpans: string[];
+        ungroundedSpans: string[];
+    }>;
+};
+/**
+ * ROI analytics API for business impact tracking
+ */
+export declare const analytics: {
+    /**
+     * Get ROI summary for the account
+     */
+    getRoiSummary(): Promise<{
+        totalRevenueSaved: number;
+        supportCostReduction: number;
+        averageResolutionTime: number;
+        customerSatisfaction: number;
+        trends: Array<{
+            date: string;
+            revenueSaved: number;
+            tracesAnalyzed: number;
+        }>;
+    }>;
+    /**
+     * Get ROI by agent
+     */
+    getRoiByAgent(agentId: string): Promise<{
+        agentId: string;
+        revenueSaved: number;
+        tracesAnalyzed: number;
+        successRate: number;
+        topIssues: Array<{
+            issue: string;
+            count: number;
+            impact: number;
+        }>;
+    }>;
+    /**
+     * Get correlation analysis
+     */
+    getCorrelations(): Promise<{
+        correlations: Array<{
+            type: string;
+            coefficient: number;
+            description: string;
+            actionableInsight: string;
+        }>;
+    }>;
+};
+/**
+ * Create a trace and analyze it in one call
+ *
+ * @example
+ * ```typescript
+ * const { trace, analysis } = await createAndAnalyze({
+ *   userMessage: 'Help me track my order',
+ *   agentResponse: 'Your order is on the way...',
+ * });
+ * ```
+ */
+export declare function createAndAnalyze(traceData: TraceOptions, options?: AnalyzeOptions): Promise<{
+    trace: TraceOptions;
+    analysis: ExplainabilityResult;
+}>;
+declare const _default: {
+    init: typeof init;
+    getTracer: typeof getTracer;
+    isInitialized: typeof isInitialized;
+    traceLLM: typeof traceLLM;
+    traceRetrieval: typeof traceRetrieval;
+    traceTool: typeof traceTool;
+    traceChain: typeof traceChain;
+    explainer: {
+        /**
+         * Analyze a trace and get explainability insights
+         *
+         * @example
+         * ```typescript
+         * const result = await explainer.analyze({
+         *   userMessage: 'Help me with my order #12345',
+         *   agentResponse: 'I found your order...',
+         *   outcome: 'success',
+         *   spans: [
+         *     { name: 'order_lookup', type: 'tool', durationMs: 150 },
+         *     { name: 'gpt-4', type: 'llm', durationMs: 2500, model: 'gpt-4' },
+         *   ],
+         * });
+         * ```
+         */
+        analyze(trace: TraceOptions, options?: AnalyzeOptions): Promise<ExplainabilityResult>;
+        /**
+         * Batch analyze multiple traces
+         *
+         * @example
+         * ```typescript
+         * const results = await explainer.analyzeBatch([
+         *   { userMessage: 'Q1', agentResponse: 'A1' },
+         *   { userMessage: 'Q2', agentResponse: 'A2' },
+         * ]);
+         * ```
+         */
+        analyzeBatch(traces: TraceOptions[], options?: AnalyzeOptions): Promise<{
+            results: ExplainabilityResult[];
+            summary: {
+                total: number;
+                successCount: number;
+                failureCount: number;
+                averageProcessingTime: number;
+            };
+        }>;
+        /**
+         * Get a previously analyzed trace
+         */
+        get(traceId: string): Promise<ExplainabilityResult>;
+        /**
+         * Search traces semantically
+         *
+         * @example
+         * ```typescript
+         * const results = await explainer.search({
+         *   query: 'order refund issues',
+         *   filters: { outcome: 'failure' },
+         *   limit: 10,
+         * });
+         * ```
+         */
+        search(params: {
+            query: string;
+            filters?: {
+                outcome?: "success" | "failure" | "partial_success";
+                minImpactScore?: number;
+                dateRange?: {
+                    from: Date;
+                    to: Date;
+                };
+            };
+            limit?: number;
+        }): Promise<{
+            results: Array<ExplainabilityResult & {
+                similarity: number;
+            }>;
+            total: number;
+        }>;
+    };
+    feedback: {
+        /**
+         * Submit feedback for a trace
+         *
+         * @example
+         * ```typescript
+         * await feedback.submit({
+         *   traceId: 'trace_123',
+         *   rating: 5,
+         *   wasHelpful: true,
+         * });
+         * ```
+         */
+        submit(options: FeedbackOptions): Promise<{
+            success: boolean;
+        }>;
+    };
+    quality: {
+        /**
+         * Get RAG evaluation scores for a trace
+         */
+        getRagScores(traceId: string): Promise<{
+            contextRelevance: number;
+            contextPrecision: number;
+            contextRecall: number;
+            groundedness: number;
+            faithfulness: number;
+            answerRelevance: number;
+            citationAccuracy: number;
+            citationCompleteness: number;
+            overallGrade: string;
+        }>;
+        /**
+         * Get hallucination report for a trace
+         */
+        getHallucinationReport(traceId: string): Promise<{
+            hasHallucinations: boolean;
+            severity: "none" | "low" | "medium" | "high";
+            confidence: number;
+            detectedTypes: Array<{
+                type: string;
+                description: string;
+                evidence: string;
+                severity: string;
+            }>;
+        }>;
+        /**
+         * Evaluate RAG quality for custom input
+         */
+        evaluateRag(input: {
+            query: string;
+            response: string;
+            contexts: Array<{
+                content: string;
+                source?: string;
+                score?: number;
+            }>;
+        }): Promise<{
+            scores: Record<string, number>;
+            grade: string;
+            groundedSpans: string[];
+            ungroundedSpans: string[];
+        }>;
+    };
+    analytics: {
+        /**
+         * Get ROI summary for the account
+         */
+        getRoiSummary(): Promise<{
+            totalRevenueSaved: number;
+            supportCostReduction: number;
+            averageResolutionTime: number;
+            customerSatisfaction: number;
+            trends: Array<{
+                date: string;
+                revenueSaved: number;
+                tracesAnalyzed: number;
+            }>;
+        }>;
+        /**
+         * Get ROI by agent
+         */
+        getRoiByAgent(agentId: string): Promise<{
+            agentId: string;
+            revenueSaved: number;
+            tracesAnalyzed: number;
+            successRate: number;
+            topIssues: Array<{
+                issue: string;
+                count: number;
+                impact: number;
+            }>;
+        }>;
+        /**
+         * Get correlation analysis
+         */
+        getCorrelations(): Promise<{
+            correlations: Array<{
+                type: string;
+                coefficient: number;
+                description: string;
+                actionableInsight: string;
+            }>;
+        }>;
+    };
+    createAndAnalyze: typeof createAndAnalyze;
+};
+export default _default;