ThinkHive SDK v4.0 - AI agent observability with business metrics, ROI analytics, and 25+ trace format support
Package Exports
@thinkhive/sdk
@thinkhive/sdk/instrumentation/langchain
@thinkhive/sdk/instrumentation/openai
@thinkhive/sdk/integrations/customer-context
@thinkhive/sdk/integrations/ticket-linking
Readme
ThinkHive SDK v4.1.0
The official JavaScript/TypeScript SDK for ThinkHive - AI Agent Observability Platform.
Features
OpenTelemetry-Based Tracing: Built on OTLP for seamless integration with existing observability tools
Run-Centric Architecture: Atomic unit of work tracking with claims, calibration, and linking
Facts vs Inferences: Claims API for separating verified facts from inferences
Deterministic Ticket Linking: 7 methods for linking runs to support tickets (Zendesk, Intercom, Salesforce, Freshdesk)
Calibrated Predictions: Brier scores and ECE for prediction accuracy
Configurable ROI Engine: Business impact calculation with customizable cost, deflection, and attribution models
Auto-Instrumentation: Works with LangChain, OpenAI, Anthropic, and more
Multi-Format Support: Normalizes traces from 25+ observability platforms
Installation
npminstall @thinkhive/sdk
Quick Start
Initialization
import{ init, runs, shutdown }from'@thinkhive/sdk';init({
apiKey:'thk_your_api_key',
serviceName:'my-ai-agent',
autoInstrument:true,
frameworks:['langchain','openai'],});// Create a run (atomic unit of work)const run =await runs.create({
agentId:'weather-agent',
conversationMessages:[{ role:'user', content:'What is the weather in San Francisco?'},{ role:'assistant', content:'The weather in San Francisco is currently 65F and sunny.'}],
outcome:'success',});console.log(`Run ID: ${run.id}`);awaitshutdown();
API Reference
Core APIs (V3)
API
Import
Description
runs
@thinkhive/sdk
Create and manage runs (atomic work units)
claims
@thinkhive/sdk
Manage facts/inferences for runs
calibration
@thinkhive/sdk
Track prediction accuracy (Brier scores)
linking
@thinkhive/sdk
Connect runs to support tickets (7 methods)
customerContext
@thinkhive/sdk
Time-series customer snapshots
roiAnalytics
@thinkhive/sdk
Configurable ROI calculation engine
agents
@thinkhive/sdk
Agent CRUD management
apiKeys
@thinkhive/sdk
API key management with scoped permissions
Assessment APIs
API
Description
humanReview
Human-in-the-loop review queues
nondeterminism
Multi-sample reliability testing
evalHealth
Metric health monitoring
deterministicGraders
Rule-based grading
conversationEval
Multi-turn conversation grading
transcriptPatterns
Pattern detection in transcripts
Legacy APIs (V2)
API
Description
issues
Clustered failure patterns
analyzer
User-selected trace analysis with cost estimation
businessMetrics
Industry-driven metrics with historical tracking
qualityMetrics
RAG scoring and hallucination detection
Runs API
import{ runs, createRunWithContext }from'@thinkhive/sdk';// Create a runconst run =await runs.create({
agentId:'support-agent',
conversationMessages:[{ role:'user', content:'Help me cancel my order'},{ role:'assistant', content:'I can help you cancel your order...'}],
outcome:'resolved',
durationMs:1500,});// List runs with filtersconst result =await runs.list({
agentId:'support-agent',
outcome:'resolved',
startedAfter:'2025-01-01',
limit:50,});// Get a specific runconst existing =await runs.get('run_abc123');// Get run statisticsconst stats =await runs.stats('support-agent');
Claims API (Facts vs Inferences)
import{ claims, isFact, isInference, getHighConfidenceClaims }from'@thinkhive/sdk';// List claims for a runconst claimList =await claims.list(runId);// Filter by typeconst facts = claimList.filter(isFact);const inferences = claimList.filter(isInference);// Get high confidence claimsconst confident =getHighConfidenceClaims(claimList,0.9);// Group by categoryconst byCategory =groupClaimsByCategory(claimList);
Calibration API
import{ calibration, calculateBrierScore, isWellCalibrated }from'@thinkhive/sdk';// Get calibration status for a prediction typeconst status =await calibration.status('agent-123','churn_risk');// Get all calibration metricsconst metrics =await calibration.allMetrics('agent-123');// Calculate Brier score locallyconst score =calculateBrierScore([{ predicted:0.8, actual:1},{ predicted:0.3, actual:0},]);if(isWellCalibrated(score)){console.log('Agent predictions are well calibrated');}
Ticket Linking (V3)
Deterministic linking between runs and support tickets using 7 methods with explicit confidence scores.
import{
linking,
generateZendeskMarker,
linkRunToTicket,
linkRunToZendeskTicket,
getBestLinkMethod,LINK_METHOD_CONFIDENCE,}from'@thinkhive/sdk';// SDK explicit linking (confidence: 1.0)const link =await linking.create({
runId:'run_abc123',
ticketId:'ticket_xyz',
method:'sdk_explicit',});// Zendesk marker linkingconst zdLink =await linking.create({
runId:'run_abc123',
externalTicketId:'12345',
platform:'zendesk',
method:'zendesk_marker',});// Convenience functionsawaitlinkRunToTicket('run_abc123','ticket_xyz');awaitlinkRunToZendeskTicket('run_abc123','12345');// Get links for a runconst links =await linking.getForRun('run_abc123');// Get links for a ticketconst ticketLinks =await linking.getForTicket('ticket_xyz');// Verify a linkawait linking.verify('link_id',{ verified:true, notes:'Confirmed by agent'});// Auto-link using all available evidenceconst autoLinked =await linking.autoLink('run_abc123');// Get link statisticsconst stats =await linking.stats();// { totalLinks, byMethod, avgConfidence, verifiedCount, unverifiedCount }// Generate a Zendesk marker to embed in responsesconst marker =generateZendeskMarker('run_abc123');// Returns: '[THID:run_abc123]'// Server-side marker generation with format optionsconst serverMarker =await linking.generateMarker({
traceId:'trace_123',
format:'html_comment',});// Delete a linkawait linking.delete('link_id');
Link Methods and Confidence
Method
Confidence
Description
sdk_explicit
1.0
Direct SDK call with ticket ID
zendesk_marker
1.0
Embedded THID marker in response
custom_field
1.0
Zendesk custom field
manual
1.0
Human-assigned
middleware_stamp
0.98
Middleware-injected trace ID
session_match
0.95
Session ID correlation
email_time_window
0.6
Email + 15min window
ROI Analytics (V3)
Configurable ROI calculation engine with customizable cost models, deflection definitions, and attribution rules.
Configuration
import{ roiAnalytics }from'@thinkhive/sdk';// Get active ROI config (auto-provisions default if none exists)const config =await roiAnalytics.getConfig();// Create custom ROI configconst newConfig =await roiAnalytics.createConfig({
costConfig:{
humanAgentCostPerHour:35,
aiCostPer1kTokens:0.01,
escalationCostMultiplier:2.5,
infrastructureMonthlyCost:200,},
deflectionConfig:{
definition:'resolved_without_human',
outcomesThatCount:['resolved'],
minConfidence:0.8,
excludeEscalated:true,},
resolutionConfig:{
definition:'customer_confirmed',
requiresSatisfaction:false,
minSatisfactionScore:null,
noRecontactWindowHours:24,},
attributionConfig:{
timeSavedValuePerHour:50,
churnPreventionAttribution:0.2,
upsellAttribution:0.1,
useActualARR:true,
defaultARRIfUnknown:10000,},});// Update config (creates new version, keeps history)const updated =await roiAnalytics.updateConfig({
costConfig:{ humanAgentCostPerHour:40},});// List config version historyconst versions =await roiAnalytics.configVersions({ limit:10});
Calculate ROI
// Calculate ROI for a date rangeconst result =await roiAnalytics.calculateV3({
startDate:'2025-01-01',
endDate:'2025-02-01',
includeBreakdown:true,
includeConfidenceIntervals:false,});console.log(`Net ROI: $${result.summary.netROI}`);console.log(`ROI %: ${result.summary.roiPercentage}%`);console.log(`Deflection Rate: ${result.metrics.deflectionRate}`);console.log(`Total Runs: ${result.metrics.totalRuns}`);// Filter by agentconst agentROI =await roiAnalytics.calculateV3({
agentId:'support-agent',
startDate:'2025-01-01',
endDate:'2025-02-01',});
ROI Trends
// Get ROI trend over timeconst trend =await roiAnalytics.trendV3({
granularity:'day',// 'day' | 'week' | 'month'
startDate:'2025-01-01',
endDate:'2025-02-01',});for(const bucket of trend.trend){console.log(`${bucket.periodStart}: ${bucket.runCount} runs, $${bucket.netROI} ROI`);}if(trend.comparison){console.log(`Improving: ${trend.comparison.isImproving}`);console.log(`Change: ${trend.comparison.changePercent}%`);}
import{ init }from'@thinkhive/sdk';init({
apiKey:'thk_your_api_key',
serviceName:'my-ai-agent',
autoInstrument:true,
frameworks:['langchain','openai','anthropic'],});// All LangChain, OpenAI, and Anthropic calls are now automatically traced