JavaScript SDK
The SupaEval JavaScript SDK works seamlessly in Node.js and modern browsers, providing a powerful and type-safe way to integrate agent evaluation into your JavaScript and TypeScript applications.
Installation
Install the SupaEval JavaScript SDK using your preferred package manager:
npm install @supaeval/js-sdkAuthentication
You'll need an API key to use the SupaEval SDK. Get your API key from the SupaEval dashboard.
Quick Start
Here's a complete example showing how to create a dataset, add test cases, and run an evaluation:
import { SupaEval } from '@supaeval/js-sdk';
// Initialize the client
const client = new SupaEval({
apiKey: process.env.SUPAEVAL_API_KEY
});
// Create a dataset
const dataset = await client.datasets.create({
name: 'my-evaluation-dataset',
description: 'Test dataset for agent evaluation'
});
// Add test cases
await dataset.addItems([
{
input: 'What is the capital of France?',
expectedOutput: 'Paris',
metadata: { difficulty: 'easy' }
},
{
input: 'Explain quantum computing',
expectedOutput: 'Quantum computing uses quantum bits...',
metadata: { difficulty: 'hard' }
}
]);
// Run evaluation
const evaluation = await client.evaluations.create({
datasetId: dataset.id,
agentEndpoint: 'https://your-agent.api/chat',
metrics: ['accuracy', 'relevance', 'faithfulness']
});
// Get results
const results = await evaluation.getResults();
console.log(`Overall Score: ${results.overallScore}`);
console.log(`Pass Rate: ${results.passRate}%`);Browser Usage
You can use the SDK in the browser via CDN or as an ES module:
<!-- Include via CDN -->
<script src="https://cdn.supaeval.com/js-sdk@latest/index.min.js"></script>
<script>
const client = new SupaEval.SupaEval({
apiKey: 'your_api_key'
});
// Use the client
async function runEvaluation() {
const evaluation = await client.evaluations.create({
datasetId: 'dataset_123',
agentEndpoint: 'https://your-agent.api/chat'
});
const results = await evaluation.getResults();
console.log(results);
}
</script>TypeScript Support
The SDK provides full TypeScript support with comprehensive type definitions:
import { SupaEval, type Evaluation, type Dataset } from '@supaeval/js-sdk';
const client = new SupaEval({
apiKey: process.env.SUPAEVAL_API_KEY!
});
// TypeScript types are fully supported
const dataset: Dataset = await client.datasets.create({
name: 'typed-dataset',
description: 'Dataset with TypeScript types'
});
const evaluation: Evaluation = await client.evaluations.create({
datasetId: dataset.id,
agentEndpoint: 'https://your-agent.api/chat',
metrics: ['accuracy', 'relevance']
});Streaming Results
Stream evaluation results in real-time for better UX:
// Stream evaluation results
const stream = await client.evaluations.stream({
datasetId: 'dataset_123',
agentEndpoint: 'https://your-agent.api/chat'
});
for await (const result of stream) {
console.log('Progress:', result.progress);
console.log('Current Score:', result.currentScore);
if (result.completed) {
console.log('Final Score:', result.finalScore);
break;
}
}Key Features
Tree Shakeable
Only bundle what you use for minimal bundle size
Promise-based
Modern async/await syntax for clean, readable code
Automatic Retries
Built-in retry logic with configurable backoff
ESM & CommonJS
Works with both module systems seamlessly