JavaScript/TypeScript SDK

v4.1.0StableLast updated: March 2026

The ThinkHive JavaScript SDK (@thinkhive/sdk) provides comprehensive tracing, guardrails, and analysis for your AI applications. Version 4.x introduces guardrails, business metrics, ROI analytics, human review, and many more capabilities.

Installation

npm install @thinkhive/sdk

yarn add @thinkhive/sdk

pnpm add @thinkhive/sdk

Requirements

Node.js: 18.0.0 or higher
TypeScript: 5.0+ (optional, but recommended)

Quick Start

Set your API key

export THINKHIVE_API_KEY=th_your_api_key

Initialize the SDK

import { init, traceLLM } from '@thinkhive/sdk';
 
init({
  serviceName: 'my-ai-agent',
  autoInstrument: true,  // Auto-instrument OpenAI, LangChain
  debug: false,          // Enable debug logging
});

Start tracing

const response = await traceLLM({
  name: 'customer-chat',
  modelName: 'gpt-4',
  provider: 'openai',
  input: 'Hello, how can I help?',
}, async () => {
  return await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
});

Configuration Options

import { init } from '@thinkhive/sdk';
 
init({
  // Required
  serviceName: 'my-ai-agent',
 
  // Authentication (can also use THINKHIVE_API_KEY env var)
  apiKey: 'thk_your_api_key',
 
  // Optional: Custom endpoint
  endpoint: 'https://app.thinkhive.ai',
 
  // Optional: Auto-instrumentation
  autoInstrument: true,
  frameworks: ['openai', 'langchain'],  // Specific frameworks
 
  // Optional: Debugging
  debug: true,
 
  // Optional: Agent identification
  agentId: 'agent_123',
});

Configuration Options Reference

Option	Type	Default	Description
`serviceName`	`string`	Required	Identifier for your service in traces
`apiKey`	`string`	`env.THINKHIVE_API_KEY`	Your ThinkHive API key
`endpoint`	`string`	`https://app.thinkhive.ai`	API endpoint URL
`autoInstrument`	`boolean`	`false`	Enable automatic instrumentation
`frameworks`	`string[]`	`['openai', 'langchain']`	Frameworks to auto-instrument
`debug`	`boolean`	`false`	Enable debug logging
`agentId`	`string`	`undefined`	Agent identifier for filtering

Core Exports

The SDK exports the following modules:

// Initialization
import { init, shutdown, isInitialized, getTracer } from '@thinkhive/sdk';
 
// Tracing functions
import { traceLLM, traceRetrieval, traceTool, traceChain } from '@thinkhive/sdk';
 
// V3 API clients
import { runs, claims, calibration, linking, customerContext } from '@thinkhive/sdk';
 
// V4 API clients
import {
  humanReview,          // Human review queue management
  nondeterminism,       // Pass@k analysis, reliability testing
  evalHealth,           // Eval health monitoring & regressions
  deterministicGraders, // Rule-based evaluation (regex, length, JSON, PII)
  conversationEval,     // Multi-turn conversation analysis
  transcriptPatterns,   // Transcript pattern detection
  agents,               // Agent CRUD
  guardrails,           // Real-time content scanning
  apiKeys,              // API key management (v2)
  roiAnalytics,         // ROI metrics and business impact
  businessMetrics,      // Business metric tracking
  qualityMetrics,       // RAG quality, hallucination detection
  issues,               // Issue management (v2)
  analyzer,             // Trace analysis engine (v2)
} from '@thinkhive/sdk';
 
// Utilities
import { isFact, isInference, calculateBrierScore } from '@thinkhive/sdk';

TypeScript Support

The SDK is written in TypeScript and exports all types:

import type {
  InitOptions,
  TraceLLMOptions,
  TraceRetrievalOptions,
  TraceToolOptions,
  TraceChainOptions,
  Run,
  Claim,
  ClaimType,
  ConfidenceCalibration,
} from '@thinkhive/sdk';

Graceful Shutdown

Always shut down the SDK when your application exits:

import { shutdown } from '@thinkhive/sdk';
 
process.on('SIGTERM', async () => {
  await shutdown();
  process.exit(0);
});
 
// Or in your cleanup code
await shutdown();

Environment Variables

Variable	Description
`THINKHIVE_API_KEY`	Your API key (required if not passed to init)
`THINKHIVE_ENDPOINT`	Custom API endpoint
`THINKHIVE_SERVICE_NAME`	Default service name
`THINKHIVE_AGENT_ID`	Default agent ID

Next Steps

Tracing - Learn about tracing LLM calls, retrievals, and tools
V3 APIs - Use the run-centric APIs
Guardrails SDK - Real-time content scanning
Framework Integrations - Auto-instrument OpenAI and LangChain
Examples - Complete working examples

Need Help? Check the Troubleshooting guide or contact support@thinkhive.ai.

Overview Tracing