shield360 1.0.0

package/dist/instrumentation/__tests__/together-trace-comparison.test.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * Cross-Language Trace Comparison Tests for Together AI Integration
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const api_1 = require("@opentelemetry/api");
+const wrapper_1 = __importDefault(require("../together/wrapper"));
+const config_1 = __importDefault(require("../../config"));
+const helpers_1 = __importDefault(require("../../helpers"));
+const base_wrapper_1 = __importDefault(require("../base-wrapper"));
+const semantic_convention_1 = __importDefault(require("../../semantic-convention"));
+jest.mock('../../../src/config');
+jest.mock('../../../src/helpers');
+jest.mock('../../../src/instrumentation/base-wrapper');
+const mockTracer = api_1.trace.getTracer('test-tracer');
+describe('Together AI Cross-Language Trace Comparison', () => {
+    let span;
+    beforeEach(() => {
+        span = mockTracer.startSpan('test-span');
+        span.setAttribute = jest.fn();
+        span.addEvent = jest.fn();
+        jest.clearAllMocks();
+        config_1.default.environment = 'shield360-testing';
+        config_1.default.applicationName = 'shield360-test';
+        config_1.default.captureMessageContent = true;
+        config_1.default.pricingInfo = {};
+        config_1.default.disableEvents = false;
+    });
+    afterEach(() => {
+        span.end();
+    });
+    describe('Chat Completion Trace Consistency', () => {
+        it('should set same attributes as Python SDK', async () => {
+            const mockArgs = [
+                {
+                    messages: [{ role: 'user', content: 'What is Together AI?' }],
+                    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                    max_tokens: 50,
+                    temperature: 0.7,
+                    top_p: 0.9,
+                    stream: false,
+                },
+            ];
+            const mockResponse = {
+                id: 'together-test-id',
+                created: Date.now(),
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                choices: [
+                    {
+                        index: 0,
+                        finish_reason: 'stop',
+                        message: { role: 'assistant', content: 'Together AI is...' },
+                    },
+                ],
+                usage: {
+                    prompt_tokens: 9,
+                    completion_tokens: 12,
+                    total_tokens: 21,
+                },
+            };
+            jest.spyOn(helpers_1.default, 'getChatModelCost').mockReturnValue(0.001);
+            await wrapper_1.default._chatCompletion({
+                args: mockArgs,
+                genAIEndpoint: 'together.chat.completions',
+                response: mockResponse,
+                span,
+            });
+            // setBaseSpanAttributes is mocked; verify it was called with Together-specific params
+            expect(base_wrapper_1.default.setBaseSpanAttributes).toHaveBeenCalledWith(span, expect.objectContaining({
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                aiSystem: 'together',
+                serverAddress: 'api.together.xyz',
+                serverPort: 443,
+            }));
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_RESPONSE_MODEL, 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo');
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_USAGE_INPUT_TOKENS, 9);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_USAGE_OUTPUT_TOKENS, 12);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_RESPONSE_ID, 'together-test-id');
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_USAGE_TOTAL_TOKENS, expect.anything());
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_CLIENT_TOKEN_USAGE, expect.anything());
+        });
+        it('should set request parameters correctly with no sentinel values', async () => {
+            const mockArgs = [
+                {
+                    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                    messages: [{ role: 'user', content: 'test message' }],
+                    max_tokens: 100,
+                    temperature: 0.7,
+                    top_p: 0.9,
+                    presence_penalty: 0.5,
+                    frequency_penalty: 0.3,
+                    seed: 42,
+                    stream: false,
+                    stop: ['STOP'],
+                    n: 2,
+                },
+            ];
+            const mockResult = {
+                id: 'test-123',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+                choices: [
+                    {
+                        message: { content: 'response text', role: 'assistant' },
+                        finish_reason: 'stop',
+                    },
+                ],
+            };
+            jest.spyOn(helpers_1.default, 'getChatModelCost').mockReturnValue(0.5);
+            const metricParams = await wrapper_1.default._chatCompletionCommonSetter({
+                args: mockArgs,
+                genAIEndpoint: 'together.chat.completions',
+                result: mockResult,
+                span,
+            });
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_TOP_P, 0.9);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_MAX_TOKENS, 100);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_TEMPERATURE, 0.7);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_PRESENCE_PENALTY, 0.5);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_FREQUENCY_PENALTY, 0.3);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_SEED, 42);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_IS_STREAM, false);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_STOP_SEQUENCES, ['STOP']);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_CHOICE_COUNT, 2);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_RESPONSE_FINISH_REASON, ['stop']);
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_OUTPUT_TYPE, 'text');
+            expect(metricParams).toEqual({
+                genAIEndpoint: 'together.chat.completions',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                user: undefined,
+                cost: 0.5,
+                aiSystem: 'together',
+            });
+        });
+        it('should not set sentinel values for optional attributes', async () => {
+            const mockArgs = [
+                {
+                    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                    messages: [{ role: 'user', content: 'test' }],
+                    stream: false,
+                },
+            ];
+            const mockResult = {
+                id: 'test-123',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                usage: { prompt_tokens: 5, completion_tokens: 10, total_tokens: 15 },
+                choices: [
+                    {
+                        message: { content: 'response', role: 'assistant' },
+                        finish_reason: 'stop',
+                    },
+                ],
+            };
+            jest.spyOn(helpers_1.default, 'getChatModelCost').mockReturnValue(0);
+            await wrapper_1.default._chatCompletionCommonSetter({
+                args: mockArgs,
+                genAIEndpoint: 'together.chat.completions',
+                result: mockResult,
+                span,
+            });
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_MAX_TOKENS, -1);
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_MAX_TOKENS, 0);
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_SEED, 0);
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_SEED, '');
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_PRESENCE_PENALTY, 0);
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_FREQUENCY_PENALTY, 0);
+            expect(span.setAttribute).not.toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_REQUEST_CHOICE_COUNT, 1);
+        });
+        it('should handle tool calls properly', async () => {
+            const mockArgs = [
+                {
+                    messages: [{ role: 'user', content: 'test message' }],
+                    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                    tools: [{ type: 'function', function: { name: 'get_weather' } }],
+                    stream: false,
+                },
+            ];
+            const mockResult = {
+                id: '123',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+                choices: [
+                    {
+                        message: {
+                            content: null,
+                            role: 'assistant',
+                            tool_calls: [
+                                {
+                                    id: 'call_123',
+                                    type: 'function',
+                                    function: { name: 'get_weather', arguments: '{"location":"SF"}' },
+                                },
+                            ],
+                        },
+                        finish_reason: 'tool_calls',
+                    },
+                ],
+            };
+            jest.spyOn(helpers_1.default, 'getChatModelCost').mockReturnValue(0.5);
+            await wrapper_1.default._chatCompletionCommonSetter({
+                args: mockArgs,
+                genAIEndpoint: 'together.chat.completions',
+                result: mockResult,
+                span,
+            });
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_TOOL_NAME, 'get_weather');
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_TOOL_CALL_ID, 'call_123');
+            expect(span.setAttribute).toHaveBeenCalledWith(semantic_convention_1.default.GEN_AI_TOOL_ARGS, '{"location":"SF"}');
+        });
+        it('should emit inference event via LoggerProvider', async () => {
+            const mockArgs = [
+                {
+                    messages: [{ role: 'user', content: 'Hello' }],
+                    model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                    stream: false,
+                },
+            ];
+            const mockResult = {
+                id: 'test-event-id',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                usage: { prompt_tokens: 5, completion_tokens: 10, total_tokens: 15 },
+                choices: [
+                    {
+                        message: { content: 'Hi there', role: 'assistant' },
+                        finish_reason: 'stop',
+                    },
+                ],
+            };
+            jest.spyOn(helpers_1.default, 'getChatModelCost').mockReturnValue(0);
+            const emitSpy = jest.spyOn(helpers_1.default, 'emitInferenceEvent').mockImplementation();
+            await wrapper_1.default._chatCompletionCommonSetter({
+                args: mockArgs,
+                genAIEndpoint: 'together.chat.completions',
+                result: mockResult,
+                span,
+            });
+            expect(emitSpy).toHaveBeenCalledWith(span, expect.objectContaining({
+                [semantic_convention_1.default.GEN_AI_OPERATION]: semantic_convention_1.default.GEN_AI_OPERATION_TYPE_CHAT,
+                [semantic_convention_1.default.GEN_AI_REQUEST_MODEL]: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                [semantic_convention_1.default.GEN_AI_RESPONSE_MODEL]: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                [semantic_convention_1.default.SERVER_ADDRESS]: 'api.together.xyz',
+                [semantic_convention_1.default.SERVER_PORT]: 443,
+                [semantic_convention_1.default.GEN_AI_RESPONSE_ID]: 'test-event-id',
+                [semantic_convention_1.default.GEN_AI_USAGE_INPUT_TOKENS]: 5,
+                [semantic_convention_1.default.GEN_AI_USAGE_OUTPUT_TOKENS]: 10,
+            }));
+        });
+        it('should call recordMetrics after span ends', async () => {
+            const mockArgs = [{ messages: [{ role: 'user', content: 'test message' }], model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo' }];
+            const mockResponse = {
+                id: '123',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+                choices: [
+                    {
+                        message: { content: 'response text', role: 'assistant' },
+                        finish_reason: 'stop',
+                    },
+                ],
+            };
+            jest
+                .spyOn(wrapper_1.default, '_chatCompletionCommonSetter')
+                .mockImplementationOnce(async () => ({
+                genAIEndpoint: 'together.chat.completions',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                user: undefined,
+                cost: 0.5,
+                aiSystem: 'together',
+            }));
+            await wrapper_1.default._chatCompletion({
+                args: mockArgs,
+                genAIEndpoint: 'together.chat.completions',
+                response: mockResponse,
+                span,
+            });
+            expect(base_wrapper_1.default.recordMetrics).toHaveBeenCalledWith(span, {
+                genAIEndpoint: 'together.chat.completions',
+                model: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+                user: undefined,
+                cost: 0.5,
+                aiSystem: 'together',
+            });
+        });
+    });
+});
+//# sourceMappingURL=together-trace-comparison.test.js.map

package/dist/instrumentation/__tests__/together-trace-comparison.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"together-trace-comparison.test.js","sourceRoot":"","sources":["../../../src/instrumentation/__tests__/together-trace-comparison.test.ts"],"names":[],"mappings":"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"}

package/dist/instrumentation/__tests__/trace-comparison-utils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Cross-Language Trace Comparison Utilities
+ *
+ * This module provides utilities to compare traces generated by Python and TypeScript
+ * Shield360 SDKs to ensure consistency across implementations.
+ * Uses SemanticConvention keys so comparisons stay in sync with the SDK.
+ */
+import { Span } from '@opentelemetry/api';
+import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+export interface NormalizedTrace {
+    spanName: string;
+    spanKind: string;
+    attributes: Record<string, any>;
+    events: Array<{
+        name: string;
+        attributes?: Record<string, any>;
+    }>;
+    status: {
+        code: string;
+        message?: string;
+    };
+    duration?: number;
+}
+export interface TraceComparisonResult {
+    match: boolean;
+    differences: string[];
+    pythonTrace?: NormalizedTrace;
+    typescriptTrace?: NormalizedTrace;
+}
+/**
+ * Normalize a TypeScript span to a comparable format
+ */
+export declare function normalizeTypeScriptSpan(span: ReadableSpan | Span): NormalizedTrace;
+/**
+ * Compare two normalized traces
+ */
+export declare function compareTraces(pythonTrace: NormalizedTrace, typescriptTrace: NormalizedTrace): TraceComparisonResult;
+/**
+ * Extract key metrics from a trace for comparison
+ */
+export declare function extractKeyMetrics(trace: NormalizedTrace): {
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    cost: number;
+    model: string;
+    operation: string;
+    system: string;
+};
+/**
+ * Compare key metrics between Python and TypeScript traces
+ */
+export declare function compareMetrics(pythonTrace: NormalizedTrace, typescriptTrace: NormalizedTrace): {
+    match: boolean;
+    differences: string[];
+};
+/**
+ * Create a test helper that validates trace consistency
+ */
+export declare function createTraceValidator(providerName: string, expectedAttributes?: string[]): {
+    validateTrace: (trace: NormalizedTrace) => {
+        valid: boolean;
+        errors: string[];
+    };
+};

package/dist/instrumentation/__tests__/trace-comparison-utils.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * Cross-Language Trace Comparison Utilities
+ *
+ * This module provides utilities to compare traces generated by Python and TypeScript
+ * Shield360 SDKs to ensure consistency across implementations.
+ * Uses SemanticConvention keys so comparisons stay in sync with the SDK.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTypeScriptSpan = normalizeTypeScriptSpan;
+exports.compareTraces = compareTraces;
+exports.extractKeyMetrics = extractKeyMetrics;
+exports.compareMetrics = compareMetrics;
+exports.createTraceValidator = createTraceValidator;
+const api_1 = require("@opentelemetry/api");
+const semantic_convention_1 = __importDefault(require("../../semantic-convention"));
+/**
+ * Normalize a TypeScript span to a comparable format
+ */
+function normalizeTypeScriptSpan(span) {
+    const spanData = span;
+    return {
+        spanName: spanData.name || '',
+        spanKind: spanData.kind?.toString() || 'INTERNAL',
+        attributes: normalizeAttributes(spanData.attributes || {}),
+        events: (spanData.events || []).map((event) => ({
+            name: event.name || '',
+            attributes: normalizeAttributes(event.attributes || {}),
+        })),
+        status: {
+            code: spanData.status?.code === api_1.SpanStatusCode.OK ? 'OK' :
+                spanData.status?.code === api_1.SpanStatusCode.ERROR ? 'ERROR' : 'UNSET',
+            message: spanData.status?.message,
+        },
+        duration: spanData.duration?.[0] ? spanData.duration[0] * 1e9 + spanData.duration[1] : undefined,
+    };
+}
+/**
+ * Normalize attributes for comparison (handles array/object differences)
+ */
+function normalizeAttributes(attrs) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        // Normalize arrays - sort for comparison
+        if (Array.isArray(value)) {
+            normalized[key] = [...value].sort();
+        }
+        // Normalize numbers (handle float precision)
+        else if (typeof value === 'number') {
+            normalized[key] = Math.round(value * 1000) / 1000; // Round to 3 decimal places
+        }
+        // Normalize strings (trim whitespace)
+        else if (typeof value === 'string') {
+            normalized[key] = value.trim();
+        }
+        // Keep other types as-is
+        else {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+/**
+ * Compare two normalized traces
+ */
+function compareTraces(pythonTrace, typescriptTrace) {
+    const differences = [];
+    // Compare span names
+    if (pythonTrace.spanName !== typescriptTrace.spanName) {
+        differences.push(`Span name mismatch: Python="${pythonTrace.spanName}", TypeScript="${typescriptTrace.spanName}"`);
+    }
+    // Compare span kind
+    if (pythonTrace.spanKind !== typescriptTrace.spanKind) {
+        differences.push(`Span kind mismatch: Python="${pythonTrace.spanKind}", TypeScript="${typescriptTrace.spanKind}"`);
+    }
+    // Compare status
+    if (pythonTrace.status.code !== typescriptTrace.status.code) {
+        differences.push(`Status code mismatch: Python="${pythonTrace.status.code}", TypeScript="${typescriptTrace.status.code}"`);
+    }
+    // Compare attributes
+    const attrDiff = compareAttributes(pythonTrace.attributes, typescriptTrace.attributes);
+    differences.push(...attrDiff);
+    // Compare events (optional - events may differ slightly)
+    const eventDiff = compareEvents(pythonTrace.events, typescriptTrace.events);
+    if (eventDiff.length > 0) {
+        differences.push(`Event differences: ${eventDiff.join(', ')}`);
+    }
+    return {
+        match: differences.length === 0,
+        differences,
+        pythonTrace,
+        typescriptTrace,
+    };
+}
+/**
+ * Compare attributes between two traces
+ */
+function compareAttributes(pythonAttrs, typescriptAttrs) {
+    const differences = [];
+    const allKeys = new Set([...Object.keys(pythonAttrs), ...Object.keys(typescriptAttrs)]);
+    // Critical attributes that must match (use SemanticConvention so keys stay in sync)
+    const criticalAttributes = [
+        semantic_convention_1.default.GEN_AI_PROVIDER_NAME,
+        semantic_convention_1.default.GEN_AI_PROVIDER_NAME_OTEL,
+        semantic_convention_1.default.GEN_AI_OPERATION,
+        semantic_convention_1.default.GEN_AI_REQUEST_MODEL,
+        semantic_convention_1.default.GEN_AI_RESPONSE_MODEL,
+        semantic_convention_1.default.GEN_AI_USAGE_INPUT_TOKENS,
+        semantic_convention_1.default.GEN_AI_USAGE_OUTPUT_TOKENS,
+        semantic_convention_1.default.GEN_AI_USAGE_TOTAL_TOKENS,
+        semantic_convention_1.default.GEN_AI_USAGE_COST,
+        semantic_convention_1.default.GEN_AI_ENDPOINT,
+        semantic_convention_1.default.GEN_AI_ENVIRONMENT,
+        semantic_convention_1.default.GEN_AI_APPLICATION_NAME,
+        semantic_convention_1.default.SERVER_ADDRESS,
+        semantic_convention_1.default.SERVER_PORT,
+        semantic_convention_1.default.GEN_AI_SDK_VERSION,
+    ];
+    for (const key of allKeys) {
+        const pythonValue = pythonAttrs[key];
+        const typescriptValue = typescriptAttrs[key];
+        const isCritical = criticalAttributes.includes(key);
+        if (pythonValue === undefined && typescriptValue !== undefined) {
+            if (isCritical) {
+                differences.push(`Missing in Python: ${key} (TypeScript has: ${typescriptValue})`);
+            }
+        }
+        else if (typescriptValue === undefined && pythonValue !== undefined) {
+            if (isCritical) {
+                differences.push(`Missing in TypeScript: ${key} (Python has: ${pythonValue})`);
+            }
+        }
+        else if (pythonValue !== typescriptValue) {
+            // For critical attributes, always report differences
+            if (isCritical) {
+                differences.push(`Attribute "${key}" mismatch: Python="${pythonValue}", TypeScript="${typescriptValue}"`);
+            }
+            // For non-critical, only report if significantly different
+            else if (typeof pythonValue === 'number' && typeof typescriptValue === 'number') {
+                const diff = Math.abs(pythonValue - typescriptValue);
+                if (diff > 0.01) { // Allow small floating point differences
+                    differences.push(`Attribute "${key}" significant difference: Python=${pythonValue}, TypeScript=${typescriptValue}`);
+                }
+            }
+        }
+    }
+    return differences;
+}
+/**
+ * Compare events between two traces
+ */
+function compareEvents(pythonEvents, typescriptEvents) {
+    const differences = [];
+    if (pythonEvents.length !== typescriptEvents.length) {
+        differences.push(`Event count mismatch: Python=${pythonEvents.length}, TypeScript=${typescriptEvents.length}`);
+    }
+    // Compare event names (order may differ)
+    const pythonEventNames = pythonEvents.map(e => e.name).sort();
+    const typescriptEventNames = typescriptEvents.map(e => e.name).sort();
+    if (JSON.stringify(pythonEventNames) !== JSON.stringify(typescriptEventNames)) {
+        differences.push(`Event names differ: Python=[${pythonEventNames.join(', ')}], TypeScript=[${typescriptEventNames.join(', ')}]`);
+    }
+    return differences;
+}
+/**
+ * Extract key metrics from a trace for comparison
+ */
+function extractKeyMetrics(trace) {
+    const attrs = trace.attributes;
+    return {
+        tokens: {
+            input: attrs[semantic_convention_1.default.GEN_AI_USAGE_INPUT_TOKENS] || 0,
+            output: attrs[semantic_convention_1.default.GEN_AI_USAGE_OUTPUT_TOKENS] || 0,
+            total: attrs[semantic_convention_1.default.GEN_AI_USAGE_TOTAL_TOKENS] || 0,
+        },
+        cost: attrs[semantic_convention_1.default.GEN_AI_USAGE_COST] || 0,
+        model: attrs[semantic_convention_1.default.GEN_AI_REQUEST_MODEL] || attrs[semantic_convention_1.default.GEN_AI_RESPONSE_MODEL] || '',
+        operation: attrs[semantic_convention_1.default.GEN_AI_OPERATION] || '',
+        system: attrs[semantic_convention_1.default.GEN_AI_PROVIDER_NAME] || attrs[semantic_convention_1.default.GEN_AI_PROVIDER_NAME_OTEL] || '',
+    };
+}
+/**
+ * Compare key metrics between Python and TypeScript traces
+ */
+function compareMetrics(pythonTrace, typescriptTrace) {
+    const pythonMetrics = extractKeyMetrics(pythonTrace);
+    const typescriptMetrics = extractKeyMetrics(typescriptTrace);
+    const differences = [];
+    // Compare tokens (allow small differences due to estimation)
+    const tokenTolerance = 5; // Allow 5 token difference
+    if (Math.abs(pythonMetrics.tokens.input - typescriptMetrics.tokens.input) > tokenTolerance) {
+        differences.push(`Input tokens differ significantly: Python=${pythonMetrics.tokens.input}, TypeScript=${typescriptMetrics.tokens.input}`);
+    }
+    if (Math.abs(pythonMetrics.tokens.output - typescriptMetrics.tokens.output) > tokenTolerance) {
+        differences.push(`Output tokens differ significantly: Python=${pythonMetrics.tokens.output}, TypeScript=${typescriptMetrics.tokens.output}`);
+    }
+    // Compare cost (allow small differences due to rounding)
+    const costTolerance = 0.0001;
+    if (Math.abs(pythonMetrics.cost - typescriptMetrics.cost) > costTolerance) {
+        differences.push(`Cost differs: Python=${pythonMetrics.cost}, TypeScript=${typescriptMetrics.cost}`);
+    }
+    // Compare model (must match exactly)
+    if (pythonMetrics.model !== typescriptMetrics.model) {
+        differences.push(`Model mismatch: Python="${pythonMetrics.model}", TypeScript="${typescriptMetrics.model}"`);
+    }
+    // Compare operation (must match exactly)
+    if (pythonMetrics.operation !== typescriptMetrics.operation) {
+        differences.push(`Operation mismatch: Python="${pythonMetrics.operation}", TypeScript="${typescriptMetrics.operation}"`);
+    }
+    // Compare system (must match exactly)
+    if (pythonMetrics.system !== typescriptMetrics.system) {
+        differences.push(`System mismatch: Python="${pythonMetrics.system}", TypeScript="${typescriptMetrics.system}"`);
+    }
+    return {
+        match: differences.length === 0,
+        differences,
+    };
+}
+/**
+ * Create a test helper that validates trace consistency
+ */
+function createTraceValidator(providerName, expectedAttributes = []) {
+    return {
+        validateTrace: (trace) => {
+            const errors = [];
+            // Check required attributes
+            for (const attr of expectedAttributes) {
+                if (!(attr in trace.attributes)) {
+                    errors.push(`Missing required attribute: ${attr}`);
+                }
+            }
+            // Check system matches provider (legacy + OTel keys from SemanticConvention)
+            const providerAttr = trace.attributes[semantic_convention_1.default.GEN_AI_PROVIDER_NAME] ?? trace.attributes[semantic_convention_1.default.GEN_AI_PROVIDER_NAME_OTEL];
+            if (providerAttr !== providerName) {
+                errors.push(`System mismatch: expected "${providerName}", got "${providerAttr}"`);
+            }
+            // Check operation is set
+            if (!trace.attributes[semantic_convention_1.default.GEN_AI_OPERATION]) {
+                errors.push('Missing operation name');
+            }
+            // Check tokens are present
+            if (!trace.attributes[semantic_convention_1.default.GEN_AI_USAGE_INPUT_TOKENS] && !trace.attributes[semantic_convention_1.default.GEN_AI_USAGE_OUTPUT_TOKENS]) {
+                errors.push('Missing token usage information');
+            }
+            return {
+                valid: errors.length === 0,
+                errors,
+            };
+        },
+    };
+}
+//# sourceMappingURL=trace-comparison-utils.js.map

package/dist/instrumentation/__tests__/trace-comparison-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-comparison-utils.js","sourceRoot":"","sources":["../../../src/instrumentation/__tests__/trace-comparison-utils.ts"],"names":[],"mappings":"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"}

package/dist/instrumentation/__tests__/transformers-trace-comparison.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cross-Language Trace Comparison Tests for local HuggingFace inference
+ * (Transformers.js) instrumentation.
+ *
+ * Verifies that the TypeScript SDK produces traces consistent with the Python
+ * `transformers` instrumentation and the OTel GenAI semantic conventions:
+ *   - text-generation reports the `chat` operation (Python parity)
+ *   - other local pipelines map to the closest OTel operation
+ *   - token usage, cache tokens, timing, and package version are stamped
+ */
+export {};