HumanJudge HumanJudge

Integration Guide

Add GrandJury SDK to your AI application and connect it with Langfuse for human evaluation tracking.

Prerequisites

Langfuse Required: HumanJudge works as an additional layer on top of Langfuse. You must have Langfuse integrated first.

1

Langfuse Account

Set up Langfuse monitoring for your AI app at langfuse.com

2

HumanJudge Account

Sign up at humanjudge.com to get your Project ID

3

Web-based AI App

Your app must be accessible via URL in Chrome browser

Installation

Option 1: CDN (Recommended)

HTML 
<script src="https://grandjury.xyz/sdk/grandjury.min.js"></script>
<script>
  GrandJury.init({
    projectId: 'proj_your_project_id'
  });
</script>

Option 2: Auto-initialization via Data Attributes

HTML 
<script
  src="https://grandjury.xyz/sdk/grandjury.min.js"
  data-grandjury-project-id="proj_your_project_id"
  data-grandjury-debug="false">
</script>

Option 3: NPM Package

Terminal 
npm install @grandjury/sdk
JavaScript 
import GrandJury from '@grandjury/sdk';

GrandJury.init({
  projectId: process.env.GRANDJURY_PROJECT_ID
});

Configuration

JavaScript 
GrandJury.init({
  // Required: Your GrandJury project ID
  projectId: 'proj_abc123_xyz',

  // Optional: API endpoint (defaults to grandjury.xyz)
  apiEndpoint: 'https://api.grandjury.xyz',

  // Optional: Session metadata
  sessionMetadata: {
    app_version: '1.0.0',
    environment: 'production'
  },

  // Optional: Auto-start session (default: true)
  autoStart: true,

  // Optional: Enable debug logging (default: false)
  enableDebug: false,

  // Optional: Enable session discovery (default: true)
  enableSessionDiscovery: true
});

Configuration Options

Option Type Default Description
projectId string required Your GrandJury project ID (format: proj_xxx)
apiEndpoint string api.grandjury.xyz API endpoint override
autoStart boolean true Auto-start session on init
enableDebug boolean false Enable console debug logging
enableSessionDiscovery boolean true Auto-detect existing session patterns

Langfuse Integration

HumanJudge integrates with Langfuse to sync human evaluation scores alongside your automated metrics.

Basic Integration

JavaScript 
import { Langfuse } from 'langfuse';
import GrandJury from '@grandjury/sdk';

// Initialize both services
await GrandJury.init({ projectId: 'proj_my_app_123' });

const langfuse = new Langfuse({
  publicKey: 'your_public_key',
  secretKey: 'your_secret_key'
});

// Create trace with automatic correlation
const trace = langfuse.trace({ name: 'user_query' });
const enhancedTrace = GrandJury.langfuse.wrapTrace(trace);

// Generate AI response
const generation = enhancedTrace.generation({
  name: 'ai_response',
  model: 'gpt-4',
  input: userQuery,
  output: aiResponse
});

// Track generation for evaluation
GrandJury.langfuse.trackGeneration(generation);

How It Works

1.

wrapTrace() adds GrandJury session ID to your Langfuse trace metadata

2.

When reviewers evaluate via Chrome extension, scores link back to the trace

3.

Human evaluation scores appear in your Langfuse dashboard

Tip: Enable enableDebug: true during development to see Langfuse correlation in console logs.

Inference Tracking

Generate unique inference IDs for each AI query to enable granular evaluation tracking.

JavaScript 
// Generate new inference ID for each user query
async function handleUserQuery(query) {
  // Create inference ID for this interaction
  const inferenceId = GrandJury.inference({
    query_type: 'chat',
    category: 'recipe_advice'
  });

  // Process AI response
  const response = await callAI(query);

  // inferenceId is automatically available to Chrome extension
  // for reviewers to evaluate this specific interaction
  return response;
}

// Get current inference ID
const currentInference = GrandJury.getCurrentInferenceId();

Inference IDs follow the format gj_inf_{timestamp}_{randomId} and are automatically exposed to the Chrome extension for evaluation.

API Reference

GrandJury.init(config)

Initialize the SDK with your project configuration.

Returns: Promise<void>

GrandJury.startSession(metadata?)

Start a new evaluation session with optional metadata.

Returns: Promise<string> - Session ID

GrandJury.stopSession()

Stop the current session and clean up resources.

Returns: Promise<void>

GrandJury.getSessionId()

Get the current session ID.

Returns: string | null

GrandJury.inference(metadata?)

Generate a new inference ID for tracking an AI interaction.

Returns: string - Inference ID

GrandJury.track(event, properties?)

Track custom analytics events.

Returns: void

GrandJury.isReady()

Check if the SDK is initialized and ready.

Returns: boolean

GrandJury.langfuse.wrapTrace(trace)

Wrap a Langfuse trace with GrandJury session correlation.

Returns: Enhanced Langfuse trace

GrandJury.langfuse.trackGeneration(generation)

Track a Langfuse generation for evaluation.

Returns: void

Examples

React Application

React 
import { useEffect } from 'react';
import GrandJury from '@grandjury/sdk';

function App() {
  useEffect(() => {
    GrandJury.init({
      projectId: process.env.REACT_APP_GRANDJURY_PROJECT_ID,
      sessionMetadata: {
        framework: 'react',
        version: '18.2.0'
      }
    });

    return () => {
      GrandJury.destroy();
    };
  }, []);

  const handleAIQuery = async (query) => {
    // Create inference for this interaction
    const inferenceId = GrandJury.inference({
      query_type: 'chat'
    });

    // Your AI logic here
    const response = await fetchAIResponse(query);
    return response;
  };

  return <div>Your app content</div>;
}

Vanilla JavaScript

HTML 
<!DOCTYPE html>
<html>
<head>
  <script src="https://grandjury.xyz/sdk/grandjury.min.js"></script>
</head>
<body>
  <script>
    GrandJury.init({
      projectId: 'proj_my_app_123',
      enableDebug: true
    }).then(() => {
      console.log('Session started:', GrandJury.getSessionId());

      // Listen for AI responses and create inference IDs
      document.getElementById('submit-btn').addEventListener('click', () => {
        const inferenceId = GrandJury.inference();
        console.log('Inference created:', inferenceId);
        // Process AI query...
      });
    });
  </script>
</body>
</html>

Troubleshooting

SDK not loading

if (typeof window.GrandJury === 'undefined') { console.error('GrandJury SDK failed to load'); }

Check network tab for script loading errors. Ensure CDN URL is correct.

Chrome extension not detecting sessions

Ensure these global variables are set after init:

console.log(window.grandjurySessionId); // Should have value console.log(window.grandjuryConfig); // Should have config

Langfuse scores not syncing

Ensure you're using GrandJury.langfuse.wrapTrace() to add session correlation to your traces.

Debug mode

Enable debug logging to troubleshoot issues:

GrandJury.init({ projectId: 'proj_your_id', enableDebug: true });

Need Help?

Questions about integration? Email support@humanjudge.com