observability-toolkit 1.8.0 → 1.8.4

package/dist/tools/query-evaluations.test.js

@@ -0,0 +1,733 @@
+/**
+ * Tests for query-evaluations tool
+ */
+import { describe, it, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert';
+import { queryEvaluations, queryEvaluationsSchema, queryEvaluationsTool } from './query-evaluations.js';
+import { LocalJsonlBackend } from '../backends/local-jsonl.js';
+import { validateToolDefinition } from '../test-helpers/tool-validators.js';
+import { validateLimitSchema, validateDateRangeSchema } from '../test-helpers/schema-validators.js';
+describe('queryEvaluations', () => {
+    // Use shared schema validators
+    validateLimitSchema(queryEvaluationsSchema, 'queryEvaluationsSchema', 50);
+    validateDateRangeSchema(queryEvaluationsSchema, 'queryEvaluationsSchema');
+    describe('schema validation', () => {
+        it('should accept empty input with defaults', () => {
+            const result = queryEvaluationsSchema.parse({});
+            assert.strictEqual(result.limit, 50);
+        });
+        it('should accept all optional parameters', () => {
+            const input = {
+                evaluationName: 'Relevance',
+                scoreMin: 0.5,
+                scoreMax: 1.0,
+                scoreLabel: 'pass',
+                responseId: 'resp-123',
+                traceId: 'trace-123',
+                sessionId: 'sess-123',
+                startDate: '2026-01-28',
+                endDate: '2026-01-28',
+                limit: 100,
+            };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.evaluationName, 'Relevance');
+            assert.strictEqual(result.scoreMin, 0.5);
+            assert.strictEqual(result.scoreMax, 1.0);
+            assert.strictEqual(result.scoreLabel, 'pass');
+        });
+        it('should enforce max limit of 1000', () => {
+            assert.throws(() => {
+                queryEvaluationsSchema.parse({ limit: 1001 });
+            });
+        });
+    });
+    describe('score range validation (P1-3)', () => {
+        let originalQueryEvaluations;
+        beforeEach(() => {
+            originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => []);
+        });
+        afterEach(() => {
+            LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+        });
+        it('should reject inverted score range (scoreMin > scoreMax)', async () => {
+            await assert.rejects(async () => queryEvaluations({ scoreMin: 0.9, scoreMax: 0.1 }), /Invalid score range.*scoreMin.*cannot exceed.*scoreMax/);
+        });
+        it('should accept valid score range (scoreMin < scoreMax)', async () => {
+            const result = await queryEvaluations({ scoreMin: 0.3, scoreMax: 0.8 });
+            assert.strictEqual(result.count, 0); // Empty mocked response
+        });
+        it('should accept equal scoreMin and scoreMax', async () => {
+            const result = await queryEvaluations({ scoreMin: 0.5, scoreMax: 0.5 });
+            assert.strictEqual(result.count, 0);
+        });
+        it('should accept scoreMin without scoreMax', async () => {
+            const result = await queryEvaluations({ scoreMin: 0.5 });
+            assert.strictEqual(result.count, 0);
+        });
+        it('should accept scoreMax without scoreMin', async () => {
+            const result = await queryEvaluations({ scoreMax: 0.8 });
+            assert.strictEqual(result.count, 0);
+        });
+    });
+    describe('handler with mocked backend', () => {
+        let originalQueryEvaluations;
+        beforeEach(() => {
+            originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+        });
+        afterEach(() => {
+            LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+        });
+        it('should return empty results when no evaluations found', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => []);
+            const result = await queryEvaluations({});
+            assert.strictEqual(result.count, 0);
+            assert.deepStrictEqual(result.evaluations, []);
+            assert.strictEqual(result.summary.averageScore, undefined);
+        });
+        it('should summarize evaluations by name and label', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                {
+                    timestamp: '2026-01-28T10:00:00Z',
+                    evaluationName: 'Relevance',
+                    scoreValue: 0.9,
+                    scoreLabel: 'pass',
+                },
+                {
+                    timestamp: '2026-01-28T10:01:00Z',
+                    evaluationName: 'Relevance',
+                    scoreValue: 0.8,
+                    scoreLabel: 'pass',
+                },
+                {
+                    timestamp: '2026-01-28T10:02:00Z',
+                    evaluationName: 'Faithfulness',
+                    scoreValue: 0.7,
+                    scoreLabel: 'fail',
+                },
+            ]);
+            const result = await queryEvaluations({});
+            assert.strictEqual(result.count, 3);
+            assert.strictEqual(result.summary.byEvaluationName['Relevance'], 2);
+            assert.strictEqual(result.summary.byEvaluationName['Faithfulness'], 1);
+            assert.strictEqual(result.summary.byScoreLabel['pass'], 2);
+            assert.strictEqual(result.summary.byScoreLabel['fail'], 1);
+        });
+        it('should calculate average score correctly', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                {
+                    timestamp: '2026-01-28T10:00:00Z',
+                    evaluationName: 'Relevance',
+                    scoreValue: 0.8,
+                },
+                {
+                    timestamp: '2026-01-28T10:01:00Z',
+                    evaluationName: 'Relevance',
+                    scoreValue: 0.9,
+                },
+                {
+                    timestamp: '2026-01-28T10:02:00Z',
+                    evaluationName: 'Relevance',
+                    scoreValue: 1.0,
+                },
+            ]);
+            const result = await queryEvaluations({});
+            assert.strictEqual(result.summary.averageScore, 0.9);
+        });
+        it('should handle evaluations without scores', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                {
+                    timestamp: '2026-01-28T10:00:00Z',
+                    evaluationName: 'ToolCorrectness',
+                    scoreLabel: 'pass',
+                    // No scoreValue
+                },
+                {
+                    timestamp: '2026-01-28T10:01:00Z',
+                    evaluationName: 'ToolCorrectness',
+                    scoreLabel: 'fail',
+                    // No scoreValue
+                },
+            ]);
+            const result = await queryEvaluations({});
+            assert.strictEqual(result.count, 2);
+            assert.strictEqual(result.summary.averageScore, undefined);
+            assert.strictEqual(result.summary.byScoreLabel['pass'], 1);
+            assert.strictEqual(result.summary.byScoreLabel['fail'], 1);
+        });
+        it('should include all fields in evaluation response', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                {
+                    timestamp: '2026-01-28T10:00:00Z',
+                    evaluationName: 'Relevance',
+                    scoreValue: 0.92,
+                    scoreLabel: 'relevant',
+                    explanation: 'Response directly addresses the query',
+                    responseId: 'resp-abc123',
+                    traceId: 'trace-xyz789',
+                    sessionId: 'sess-def456',
+                },
+            ]);
+            const result = await queryEvaluations({});
+            const evaluation = result.evaluations[0];
+            assert.strictEqual(evaluation.timestamp, '2026-01-28T10:00:00Z');
+            assert.strictEqual(evaluation.evaluationName, 'Relevance');
+            assert.strictEqual(evaluation.scoreValue, 0.92);
+            assert.strictEqual(evaluation.scoreLabel, 'relevant');
+            assert.strictEqual(evaluation.explanation, 'Response directly addresses the query');
+            assert.strictEqual(evaluation.responseId, 'resp-abc123');
+            assert.strictEqual(evaluation.traceId, 'trace-xyz789');
+            assert.strictEqual(evaluation.sessionId, 'sess-def456');
+        });
+        it('should limit returned evaluations to 20', async () => {
+            const manyEvaluations = Array.from({ length: 30 }, (_, i) => ({
+                timestamp: `2026-01-28T10:${String(i).padStart(2, '0')}:00Z`,
+                evaluationName: 'Relevance',
+                scoreValue: 0.8 + (i * 0.01),
+            }));
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => manyEvaluations);
+            const result = await queryEvaluations({});
+            assert.strictEqual(result.count, 30);
+            assert.strictEqual(result.evaluations.length, 20);
+        });
+    });
+    describe('OTel GenAI compliance', () => {
+        let originalQueryEvaluations;
+        beforeEach(() => {
+            originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+        });
+        afterEach(() => {
+            LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+        });
+        it('should accept evaluationName filter', () => {
+            const input = { evaluationName: 'Relevance' };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.evaluationName, 'Relevance');
+        });
+        it('should accept score range filters', () => {
+            const input = { scoreMin: 0.5, scoreMax: 0.9 };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.scoreMin, 0.5);
+            assert.strictEqual(result.scoreMax, 0.9);
+        });
+        it('should accept scoreLabel filter', () => {
+            const input = { scoreLabel: 'pass' };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.scoreLabel, 'pass');
+        });
+        it('should accept responseId filter for correlation', () => {
+            const input = { responseId: 'resp-12345' };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.responseId, 'resp-12345');
+        });
+        it('should accept traceId filter for trace correlation', () => {
+            const input = { traceId: 'trace-12345' };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.traceId, 'trace-12345');
+        });
+        it('should accept sessionId filter for session-scoped queries', () => {
+            const input = { sessionId: 'session-12345' };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.sessionId, 'session-12345');
+        });
+    });
+    // Use shared tool definition validator
+    validateToolDefinition(queryEvaluationsTool, 'obs_query_evaluations', queryEvaluationsSchema, queryEvaluations, ['gen_ai.evaluation.result', 'aggregations']);
+    describe('aggregation schema', () => {
+        it('should accept aggregation parameter', () => {
+            const input = { aggregation: 'avg' };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.strictEqual(result.aggregation, 'avg');
+        });
+        it('should accept all aggregation types', () => {
+            const types = ['avg', 'min', 'max', 'count', 'p50', 'p95', 'p99'];
+            for (const type of types) {
+                const result = queryEvaluationsSchema.parse({ aggregation: type });
+                assert.strictEqual(result.aggregation, type);
+            }
+        });
+        it('should reject invalid aggregation type', () => {
+            assert.throws(() => {
+                queryEvaluationsSchema.parse({ aggregation: 'invalid' });
+            });
+        });
+        it('should accept groupBy parameter', () => {
+            const input = { groupBy: ['evaluationName'] };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.deepStrictEqual(result.groupBy, ['evaluationName']);
+        });
+        it('should accept multiple groupBy fields', () => {
+            const input = { groupBy: ['evaluationName', 'scoreLabel'] };
+            const result = queryEvaluationsSchema.parse(input);
+            assert.deepStrictEqual(result.groupBy, ['evaluationName', 'scoreLabel']);
+        });
+        it('should reject invalid groupBy field', () => {
+            assert.throws(() => {
+                queryEvaluationsSchema.parse({ groupBy: ['invalidField'] });
+            });
+        });
+    });
+    describe('aggregation handler', () => {
+        let originalQueryEvaluations;
+        beforeEach(() => {
+            originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+        });
+        afterEach(() => {
+            LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+        });
+        it('should calculate avg aggregation', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 1.0 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'avg' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations.length, 1);
+            assert.strictEqual(result.summary.aggregations[0].value, 0.9);
+            assert.strictEqual(result.summary.aggregations[0].count, 3);
+        });
+        it('should calculate min aggregation', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.5 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'min' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].value, 0.5);
+        });
+        it('should calculate max aggregation', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.5 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'max' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].value, 0.9);
+        });
+        it('should calculate count aggregation', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.5 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Faithfulness', scoreLabel: 'pass' },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'count' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].count, 3);
+            assert.strictEqual(result.summary.aggregations[0].value, 3);
+        });
+        it('should calculate p50 percentile', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.1 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.5 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'p50' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].value, 0.5);
+        });
+        it('should calculate p95 percentile with linear interpolation', async () => {
+            const values = Array.from({ length: 100 }, (_, i) => ({
+                timestamp: '2026-01-28T10:00:00Z',
+                evaluationName: 'Relevance',
+                scoreValue: (i + 1) / 100,
+            }));
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => values);
+            const result = await queryEvaluations({ aggregation: 'p95', limit: 1000 });
+            assert.ok(result.summary.aggregations);
+            // R-7 linear interpolation: rank = 0.95 * 99 = 94.05
+            // Interpolate between index 94 (0.95) and index 95 (0.96)
+            const value = result.summary.aggregations[0].value;
+            assert.ok(value >= 0.95 && value <= 0.96, `Expected p95 between 0.95-0.96, got ${value}`);
+        });
+        it('should calculate p99 percentile with linear interpolation', async () => {
+            const values = Array.from({ length: 100 }, (_, i) => ({
+                timestamp: '2026-01-28T10:00:00Z',
+                evaluationName: 'Relevance',
+                scoreValue: (i + 1) / 100,
+            }));
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => values);
+            const result = await queryEvaluations({ aggregation: 'p99', limit: 1000 });
+            assert.ok(result.summary.aggregations);
+            // R-7 linear interpolation: rank = 0.99 * 99 = 98.01
+            // Interpolate between index 98 (0.99) and index 99 (1.00)
+            const value = result.summary.aggregations[0].value;
+            assert.ok(value >= 0.99 && value <= 1.0, `Expected p99 between 0.99-1.0, got ${value}`);
+        });
+        it('should group by evaluationName', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Faithfulness', scoreValue: 0.7 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'avg', groupBy: ['evaluationName'] });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations.length, 2);
+            const relevance = result.summary.aggregations.find(a => a.evaluationName === 'Relevance');
+            const faithfulness = result.summary.aggregations.find(a => a.evaluationName === 'Faithfulness');
+            assert.ok(relevance);
+            assert.ok(Math.abs((relevance.value ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${relevance.value}`);
+            assert.strictEqual(relevance.count, 2);
+            assert.ok(faithfulness);
+            assert.strictEqual(faithfulness.value, 0.7);
+            assert.strictEqual(faithfulness.count, 1);
+        });
+        it('should group by scoreLabel', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, scoreLabel: 'pass' },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.8, scoreLabel: 'pass' },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.3, scoreLabel: 'fail' },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'avg', groupBy: ['scoreLabel'] });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations.length, 2);
+            const pass = result.summary.aggregations.find(a => a.scoreLabel === 'pass');
+            const fail = result.summary.aggregations.find(a => a.scoreLabel === 'fail');
+            assert.ok(pass);
+            assert.ok(Math.abs((pass.value ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${pass.value}`);
+            assert.ok(fail);
+            assert.strictEqual(fail.value, 0.3);
+        });
+        it('should group by multiple fields', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, scoreLabel: 'pass' },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.3, scoreLabel: 'fail' },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Faithfulness', scoreValue: 0.8, scoreLabel: 'pass' },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'count', groupBy: ['evaluationName', 'scoreLabel'] });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations.length, 3);
+        });
+        it('should handle empty results with aggregation', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => []);
+            const result = await queryEvaluations({ aggregation: 'avg' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations.length, 0);
+        });
+        it('should handle evaluations without scores in aggregation', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'ToolCorrectness', scoreLabel: 'pass' },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'ToolCorrectness', scoreLabel: 'fail' },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'avg' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].count, 2);
+            assert.strictEqual(result.summary.aggregations[0].value, undefined);
+        });
+        it('should not include aggregations when aggregation not requested', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+            ]);
+            const result = await queryEvaluations({});
+            assert.strictEqual(result.summary.aggregations, undefined);
+        });
+        // P1-2: min/max should return undefined, not Infinity, when no scores
+        it('should return undefined for min aggregation when no scores (P1-2)', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'ToolCorrectness', scoreLabel: 'pass' },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'ToolCorrectness', scoreLabel: 'fail' },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'min' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].count, 2);
+            assert.strictEqual(result.summary.aggregations[0].value, undefined);
+        });
+        it('should return undefined for max aggregation when no scores (P1-2)', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'ToolCorrectness', scoreLabel: 'pass' },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'max' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].value, undefined);
+        });
+        // P1-1: Linear interpolation percentile tests
+        it('should calculate p50 with linear interpolation for even-length array (P1-1)', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.1 },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.2 },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.3 },
+                { timestamp: '2026-01-28T10:03:00Z', evaluationName: 'Relevance', scoreValue: 0.4 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'p50' });
+            assert.ok(result.summary.aggregations);
+            // R-7 method: rank = 0.5 * (4-1) = 1.5, interpolate between index 1 (0.2) and 2 (0.3)
+            // value = 0.2 * 0.5 + 0.3 * 0.5 = 0.25
+            assert.strictEqual(result.summary.aggregations[0].value, 0.25);
+        });
+        it('should handle single value for percentile (P1-1)', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.75 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'p95' });
+            assert.ok(result.summary.aggregations);
+            assert.strictEqual(result.summary.aggregations[0].value, 0.75);
+        });
+        // P1-3: Empty string scoreLabel normalization tests
+        it('should treat empty string scoreLabel as missing (P1-3)', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8, scoreLabel: '' },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9, scoreLabel: '  ' },
+                { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.7, scoreLabel: 'pass' },
+            ]);
+            const result = await queryEvaluations({});
+            // Empty and whitespace-only labels should not be counted
+            assert.strictEqual(result.summary.byScoreLabel['pass'], 1);
+            assert.strictEqual(result.summary.byScoreLabel[''], undefined);
+            assert.strictEqual(result.summary.byScoreLabel['  '], undefined);
+        });
+        it('should group empty scoreLabels together (P1-3)', async () => {
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8, scoreLabel: '' },
+                { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+            ]);
+            const result = await queryEvaluations({ aggregation: 'count', groupBy: ['scoreLabel'] });
+            assert.ok(result.summary.aggregations);
+            // Both should be grouped together as missing label
+            assert.strictEqual(result.summary.aggregations.length, 1);
+            assert.strictEqual(result.summary.aggregations[0].count, 2);
+        });
+    });
+    describe('score range validation (P2-2)', () => {
+        let originalQueryEvaluations;
+        beforeEach(() => {
+            originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+            LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => []);
+        });
+        afterEach(() => {
+            LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+        });
+        it('should reject NaN scoreMin (via Zod)', async () => {
+            await assert.rejects(async () => queryEvaluations({ scoreMin: NaN }), /received.*nan/i);
+        });
+        it('should reject NaN scoreMax (via Zod)', async () => {
+            await assert.rejects(async () => queryEvaluations({ scoreMax: NaN }), /received.*nan/i);
+        });
+        it('should reject Infinity scoreMin', async () => {
+            await assert.rejects(async () => queryEvaluations({ scoreMin: Infinity }), /Invalid scoreMin.*finite number/);
+        });
+        it('should reject -Infinity scoreMax', async () => {
+            await assert.rejects(async () => queryEvaluations({ scoreMax: -Infinity }), /Invalid scoreMax.*finite number/);
+        });
+        it('should accept negative score ranges', async () => {
+            const result = await queryEvaluations({ scoreMin: -1.0, scoreMax: 0.5 });
+            assert.strictEqual(result.count, 0);
+        });
+    });
+    describe('evaluator field (Phase 3)', () => {
+        describe('schema validation', () => {
+            it('should accept evaluator filter', () => {
+                const input = { evaluator: 'gpt-4-as-judge' };
+                const result = queryEvaluationsSchema.parse(input);
+                assert.strictEqual(result.evaluator, 'gpt-4-as-judge');
+            });
+            it('should accept evaluatorType filter', () => {
+                const input = { evaluatorType: 'llm' };
+                const result = queryEvaluationsSchema.parse(input);
+                assert.strictEqual(result.evaluatorType, 'llm');
+            });
+            it('should accept all valid evaluatorType values', () => {
+                const types = ['llm', 'human', 'rule', 'classifier'];
+                for (const type of types) {
+                    const result = queryEvaluationsSchema.parse({ evaluatorType: type });
+                    assert.strictEqual(result.evaluatorType, type);
+                }
+            });
+            it('should reject invalid evaluatorType', () => {
+                assert.throws(() => {
+                    queryEvaluationsSchema.parse({ evaluatorType: 'invalid' });
+                });
+            });
+            it('should accept evaluator in groupBy', () => {
+                const input = { groupBy: ['evaluator'] };
+                const result = queryEvaluationsSchema.parse(input);
+                assert.deepStrictEqual(result.groupBy, ['evaluator']);
+            });
+            it('should accept evaluator with other groupBy fields', () => {
+                const input = { groupBy: ['evaluationName', 'evaluator'] };
+                const result = queryEvaluationsSchema.parse(input);
+                assert.deepStrictEqual(result.groupBy, ['evaluationName', 'evaluator']);
+            });
+        });
+        describe('handler with mocked backend', () => {
+            let originalQueryEvaluations;
+            beforeEach(() => {
+                originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+            });
+            afterEach(() => {
+                LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+            });
+            it('should include evaluator and evaluatorType in response', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    {
+                        timestamp: '2026-01-28T10:00:00Z',
+                        evaluationName: 'Relevance',
+                        scoreValue: 0.92,
+                        evaluator: 'gpt-4-as-judge',
+                        evaluatorType: 'llm',
+                    },
+                ]);
+                const result = await queryEvaluations({});
+                const evaluation = result.evaluations[0];
+                assert.strictEqual(evaluation.evaluator, 'gpt-4-as-judge');
+                assert.strictEqual(evaluation.evaluatorType, 'llm');
+            });
+            it('should summarize evaluations by evaluator', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.8, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.85, evaluator: 'human-reviewer' },
+                ]);
+                const result = await queryEvaluations({});
+                assert.strictEqual(result.summary.byEvaluator['gpt-4-as-judge'], 2);
+                assert.strictEqual(result.summary.byEvaluator['human-reviewer'], 1);
+            });
+            it('should not count evaluations without evaluator in byEvaluator', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.8 }, // no evaluator
+                ]);
+                const result = await queryEvaluations({});
+                assert.strictEqual(result.summary.byEvaluator['gpt-4-as-judge'], 1);
+                assert.strictEqual(Object.keys(result.summary.byEvaluator).length, 1);
+            });
+            it('should group by evaluator', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.8, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.7, evaluator: 'human-reviewer' },
+                ]);
+                const result = await queryEvaluations({ aggregation: 'avg', groupBy: ['evaluator'] });
+                assert.ok(result.summary.aggregations);
+                assert.strictEqual(result.summary.aggregations.length, 2);
+                const gpt4 = result.summary.aggregations.find(a => a.evaluator === 'gpt-4-as-judge');
+                const human = result.summary.aggregations.find(a => a.evaluator === 'human-reviewer');
+                assert.ok(gpt4);
+                assert.ok(Math.abs((gpt4.value ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${gpt4.value}`);
+                assert.strictEqual(gpt4.count, 2);
+                assert.ok(human);
+                assert.strictEqual(human.value, 0.7);
+                assert.strictEqual(human.count, 1);
+            });
+            it('should group by evaluationName and evaluator', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Faithfulness', scoreValue: 0.8, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.7, evaluator: 'human-reviewer' },
+                ]);
+                const result = await queryEvaluations({ aggregation: 'count', groupBy: ['evaluationName', 'evaluator'] });
+                assert.ok(result.summary.aggregations);
+                assert.strictEqual(result.summary.aggregations.length, 3);
+            });
+            it('should handle evaluations without evaluator in groupBy', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.9, evaluator: 'gpt-4-as-judge' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.8 }, // no evaluator
+                ]);
+                const result = await queryEvaluations({ aggregation: 'count', groupBy: ['evaluator'] });
+                assert.ok(result.summary.aggregations);
+                // Should have two groups: one with evaluator, one without
+                assert.strictEqual(result.summary.aggregations.length, 2);
+            });
+            it('should include all evaluatorType values in response', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', evaluatorType: 'llm' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'ToolUse', evaluatorType: 'rule' },
+                    { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'UserSatisfaction', evaluatorType: 'human' },
+                    { timestamp: '2026-01-28T10:03:00Z', evaluationName: 'Intent', evaluatorType: 'classifier' },
+                ]);
+                const result = await queryEvaluations({});
+                // Results are sorted by timestamp DESC, so order is reversed
+                const types = result.evaluations.map(e => e.evaluatorType).sort();
+                assert.deepStrictEqual(types, ['classifier', 'human', 'llm', 'rule']);
+            });
+        });
+    });
+    describe('scoreUnit field (Phase 1)', () => {
+        describe('handler with mocked backend', () => {
+            let originalQueryEvaluations;
+            beforeEach(() => {
+                originalQueryEvaluations = LocalJsonlBackend.prototype.queryEvaluations;
+            });
+            afterEach(() => {
+                LocalJsonlBackend.prototype.queryEvaluations = originalQueryEvaluations;
+            });
+            it('should include scoreUnit in response', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    {
+                        timestamp: '2026-01-28T10:00:00Z',
+                        evaluationName: 'Relevance',
+                        scoreValue: 85,
+                        scoreUnit: 'percentage',
+                    },
+                ]);
+                const result = await queryEvaluations({});
+                assert.strictEqual(result.evaluations[0].scoreUnit, 'percentage');
+            });
+            it('should normalize percentage scores for averageScore', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 80, scoreUnit: 'percentage' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 90, scoreUnit: 'percentage' },
+                ]);
+                const result = await queryEvaluations({});
+                // (80/100 + 90/100) / 2 = 0.85
+                assert.ok(Math.abs((result.summary.averageScore ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${result.summary.averageScore}`);
+            });
+            it('should not change ratio_0_1 scores for averageScore', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8, scoreUnit: 'ratio_0_1' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9, scoreUnit: 'ratio_0_1' },
+                ]);
+                const result = await queryEvaluations({});
+                // (0.8 + 0.9) / 2 = 0.85
+                assert.ok(Math.abs((result.summary.averageScore ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${result.summary.averageScore}`);
+            });
+            it('should not change scores without unit for averageScore', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 0.8 },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9 },
+                ]);
+                const result = await queryEvaluations({});
+                // (0.8 + 0.9) / 2 = 0.85
+                assert.ok(Math.abs((result.summary.averageScore ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${result.summary.averageScore}`);
+            });
+            it('should handle mixed units for averageScore', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 80, scoreUnit: 'percentage' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 0.9, scoreUnit: 'ratio_0_1' },
+                    { timestamp: '2026-01-28T10:02:00Z', evaluationName: 'Relevance', scoreValue: 0.85 }, // no unit, defaults to ratio
+                ]);
+                const result = await queryEvaluations({});
+                // (0.8 + 0.9 + 0.85) / 3 = 0.85
+                assert.ok(Math.abs((result.summary.averageScore ?? 0) - 0.85) < 0.0001, `Expected ~0.85, got ${result.summary.averageScore}`);
+            });
+            it('should handle percent as alias for percentage', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 100, scoreUnit: 'percent' },
+                ]);
+                const result = await queryEvaluations({});
+                // 100/100 = 1.0
+                assert.strictEqual(result.summary.averageScore, 1.0);
+            });
+            it('should handle case-insensitive unit names', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 50, scoreUnit: 'PERCENTAGE' },
+                    { timestamp: '2026-01-28T10:01:00Z', evaluationName: 'Relevance', scoreValue: 50, scoreUnit: 'Percentage' },
+                ]);
+                const result = await queryEvaluations({});
+                // (50/100 + 50/100) / 2 = 0.5
+                assert.strictEqual(result.summary.averageScore, 0.5);
+            });
+            it('should not normalize unknown units', async () => {
+                LocalJsonlBackend.prototype.queryEvaluations = mock.fn(async () => [
+                    { timestamp: '2026-01-28T10:00:00Z', evaluationName: 'Relevance', scoreValue: 5, scoreUnit: 'stars_1_5' },
+                ]);
+                const result = await queryEvaluations({});
+                // Unknown unit, keep as-is
+                assert.strictEqual(result.summary.averageScore, 5);
+            });
+        });
+    });
+});
+//# sourceMappingURL=query-evaluations.test.js.map