Getting StartedYour First Trace

Your First Trace

In this tutorial, you’ll build a simple RAG (Retrieval-Augmented Generation) chatbot that’s fully traced with ThinkHive. By the end, you’ll have:

  • A working chatbot with retrieval and LLM calls
  • Complete observability into every operation
  • Automatic quality evaluation

What We’re Building

Prerequisites

  • Node.js 18+ or Python 3.8+
  • ThinkHive API key
  • OpenAI API key

Project Setup

mkdir thinkhive-demo && cd thinkhive-demo
npm init -y
npm install @thinkhive/sdk openai
    • package.json
    • index.js
    • .env

Step-by-Step Implementation

Configure Environment

Create a .env file:

THINKHIVE_API_KEY=thk_your_api_key
OPENAI_API_KEY=sk-your_openai_key

Initialize ThinkHive

index.js
import 'dotenv/config';
import { init, traceLLM, traceRetrieval, traceChain } from '@thinkhive/sdk';
import OpenAI from 'openai';
 
// Initialize ThinkHive
init({
  serviceName: 'rag-demo',
  debug: true,  // Enable debug logging
});
 
const openai = new OpenAI();

Create a Simple Knowledge Base

index.js
// Simple in-memory knowledge base
const knowledgeBase = [
  {
    id: 'doc1',
    content: 'ThinkHive is an AI observability platform that helps teams monitor and improve their AI agents.',
    embedding: [0.1, 0.2, 0.3], // Simplified for demo
  },
  {
    id: 'doc2',
    content: 'ThinkHive supports RAG evaluation, hallucination detection, and drift monitoring.',
    embedding: [0.2, 0.3, 0.4],
  },
  {
    id: 'doc3',
    content: 'ThinkHive integrates with OpenAI, LangChain, and supports OpenTelemetry for tracing.',
    embedding: [0.3, 0.4, 0.5],
  },
];
 
// Simple similarity search (in production, use a vector database)
function simpleSearch(query, topK = 2) {
  // Return top K documents (simplified - no actual embedding comparison)
  return knowledgeBase.slice(0, topK);
}

Implement Traced Retrieval

index.js
async function searchDocuments(query) {
  // Wrap retrieval in a traced span
  const documents = await traceRetrieval({
    name: 'knowledge-search',
    query: query,
    topK: 2,
  }, async () => {
    const results = simpleSearch(query, 2);
    return results;
  });
 
  return documents;
}

Implement Traced LLM Call

index.js
async function generateResponse(query, context) {
  const response = await traceLLM({
    name: 'answer-generation',
    modelName: 'gpt-4',
    provider: 'openai',
    input: query,
  }, async () => {
    const completion = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        {
          role: 'system',
          content: `You are a helpful assistant. Answer based on this context:\n\n${context}`,
        },
        {
          role: 'user',
          content: query,
        },
      ],
      temperature: 0.7,
    });
    return completion;
  });
 
  return response.choices[0].message.content;
}

Create the RAG Pipeline

index.js
async function ragChat(userQuestion) {
  // Wrap entire pipeline in a chain trace
  const answer = await traceChain({
    name: 'rag-pipeline',
    input: { question: userQuestion },
  }, async () => {
    // Step 1: Retrieve relevant documents
    const documents = await searchDocuments(userQuestion);
 
    // Step 2: Build context from documents
    const context = documents.map(d => d.content).join('\n\n');
 
    // Step 3: Generate response
    const response = await generateResponse(userQuestion, context);
 
    return response;
  });
 
  return answer;
}
 
// Main execution
async function main() {
  console.log('Starting RAG Demo...\n');
 
  const questions = [
    'What is ThinkHive?',
    'What features does ThinkHive support?',
    'How does ThinkHive integrate with other tools?',
  ];
 
  for (const question of questions) {
    console.log(`Question: ${question}`);
    const answer = await ragChat(question);
    console.log(`Answer: ${answer}\n`);
  }
 
  console.log('Check your traces at https://app.thinkhive.ai/traces');
}
 
main().catch(console.error);

Run and View Traces

node index.js

What You’ll See in ThinkHive

After running your application, open app.thinkhive.ai/traces to see:

Trace Timeline

A visual timeline showing:

  • The parent rag-pipeline chain span
  • Nested knowledge-search retrieval span
  • Nested answer-generation LLM span

Span Details

For each span, you’ll see:

  • Duration: How long each operation took
  • Input/Output: What went in and came out
  • Token Usage: For LLM calls
  • Retrieved Documents: For retrieval operations

Quality Metrics

ThinkHive automatically evaluates:

  • Groundedness: Is the response supported by the retrieved documents?
  • Hallucination Risk: Are there unsupported claims?
  • Latency Analysis: Where is time being spent?

Next Steps

Congratulations! You’ve built a fully traced RAG application. Now explore:

Pro Tip: Add custom attributes to your spans for richer analysis:

await traceLLM({
  name: 'answer-generation',
  modelName: 'gpt-4',
  provider: 'openai',
  metadata: {
    customerId: 'cust_123',
    channel: 'chat',
    intent: 'product_inquiry',
  },
}, async () => { /* ... */ });