@atlanai/sdk 0.1.1 → 0.2.2

package/dist/tracing/client.d.ts

@@ -77,6 +77,8 @@ export declare class AtlanAI {
      * acquired from it flow through the Atlan pipeline (allowlist + enrichment). */
     get tracerProvider(): BasicTracerProvider | null;
     getTracer(): Tracer;
+    /** Return the active OTel span through the Atlan ergonomic span surface. */
+    currentSpan(): AtlanSpan;
     /**
      * Create or refresh a Visitor and return its canonical artifact identity.
      * This never changes process-global identity; carry visitor.id through

package/dist/tracing/client.js

@@ -254,6 +254,13 @@ class AtlanAI {
         const provider = this.provider ?? api_1.trace.getTracerProvider();
         return provider.getTracer(span_filter_js_1.ATLAN_SDK_SCOPE, version_js_1.SDK_VERSION);
     }
+    /** Return the active OTel span through the Atlan ergonomic span surface. */
+    currentSpan() {
+        const active = api_1.trace.getSpan(api_1.context.active());
+        if (active === undefined)
+            return (0, spans_js_1.noopSpan)(this.config);
+        return new spans_js_1.AtlanSpan(active, this.config, this.mask, this.getTracer());
+    }
     /**
      * Create or refresh a Visitor and return its canonical artifact identity.
      * This never changes process-global identity; carry visitor.id through
@@ -274,8 +281,9 @@ class AtlanAI {
         else {
             ({ context, asRoot } = remoteParentContext(options.traceContext, api_1.context.active()));
         }
-        const otelSpan = this.getTracer().startSpan(name, options.startTime !== undefined ? { startTime: options.startTime } : {}, context);
-        const span = new spans_js_1.AtlanSpan(otelSpan, this.config, this.mask);
+        const tracer = this.getTracer();
+        const otelSpan = tracer.startSpan(name, options.startTime !== undefined ? { startTime: options.startTime } : {}, context);
+        const span = new spans_js_1.AtlanSpan(otelSpan, this.config, this.mask, tracer);
         span._initialize(options.asType ?? "task", asRoot);
         if (options.fields)
             span.update(options.fields);
@@ -290,8 +298,9 @@ class AtlanAI {
         if (this.spanProcessor === null)
             return fn((0, spans_js_1.noopSpan)(this.config));
         const { context, asRoot } = remoteParentContext(options.traceContext, api_1.context.active());
-        const otelSpan = this.getTracer().startSpan(name, options.startTime !== undefined ? { startTime: options.startTime } : {}, context);
-        const span = new spans_js_1.AtlanSpan(otelSpan, this.config, this.mask);
+        const tracer = this.getTracer();
+        const otelSpan = tracer.startSpan(name, options.startTime !== undefined ? { startTime: options.startTime } : {}, context);
+        const span = new spans_js_1.AtlanSpan(otelSpan, this.config, this.mask, tracer);
         span._initialize(options.asType ?? "task", asRoot);
         if (options.fields)
             span.update(options.fields);

package/dist/tracing/compat.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Low-friction tracing compatibility helpers.
+ *
+ * The implementation deliberately reuses the SDK's OTel pipeline: ended spans
+ * enter its bounded background batcher, `flush()` drains that same queue, and
+ * third-party OTel instrumentation shares the same provider. There is no
+ * second transport or vendor-specific event format to keep in sync.
+ */
+import { type AtlanAI, type InitOptions, type StartSpanOptions } from "./client.js";
+import { type ObserveOptions } from "./observe.js";
+import type { AtlanSpan, UpdateFields } from "./spans.js";
+type AnyFunction = (...args: any[]) => any;
+export interface InitLoggerOptions extends Omit<InitOptions, "exportMode" | "serviceName"> {
+    /** Braintrust migration alias. In Atlan this becomes the trace service name. */
+    projectName?: string;
+    /** Used as the service name when `projectName` is absent. */
+    projectId?: string;
+    /** Native Atlan spelling; takes precedence over the migration aliases. */
+    serviceName?: string;
+    /** Background batching is on by default. `false` switches to immediate export. */
+    asyncFlush?: boolean;
+    /** Export every OTel span. Defaults to true for logger-style observability. */
+    captureAll?: boolean;
+    /** Set this logger as the process current logger. Defaults to true. */
+    setCurrent?: boolean;
+}
+export interface StartSpanArgs extends StartSpanOptions {
+    name?: string;
+    type?: string;
+    event?: UpdateFields;
+}
+export interface LogEvent extends UpdateFields {
+    name?: string;
+    type?: string;
+}
+export interface LoggedSpan {
+    traceId: string;
+    spanId: string;
+}
+export interface WrapTracedOptions extends Omit<ObserveOptions, "asType"> {
+    type?: string;
+    asType?: string;
+    /** Suppress automatic argument and return-value capture. */
+    noTraceIO?: boolean;
+}
+/** A small logger facade over one Atlan OTel client. */
+export declare class Logger {
+    readonly client: AtlanAI;
+    readonly projectName: string;
+    readonly asyncFlush: boolean;
+    constructor(client: AtlanAI, projectName: string, asyncFlush: boolean);
+    startSpan(name: string, options?: StartSpanOptions): AtlanSpan;
+    startSpan(args?: StartSpanArgs): AtlanSpan;
+    /** Run a callback with an automatically ended, ambient current span. */
+    traced<T>(callback: (span: AtlanSpan) => T, args?: StartSpanArgs): T;
+    /** Log one complete root event. Delivery is asynchronous by default. */
+    log(event: LogEvent): LoggedSpan;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Initialize production tracing with Braintrust-style logger ergonomics.
+ *
+ * All OTel spans are accepted by default and handed to the existing background
+ * batch processor. Initialize this before provider/framework clients so their
+ * instrumentation acquires the same global OTel provider.
+ */
+export declare function initLogger(options?: InitLoggerOptions): Logger;
+/** The logger most recently initialized with `setCurrent !== false`. */
+export declare function currentLogger(): Logger | undefined;
+/** Active span, or a safe no-op span when no traced scope is active. */
+export declare function currentSpan(): AtlanSpan;
+/** Start a manual span from the current tracing client. */
+export declare function startSpan(name: string, options?: StartSpanOptions): AtlanSpan;
+export declare function startSpan(args?: StartSpanArgs): AtlanSpan;
+/** Run a callback in an automatically ended current span. */
+export declare function traced<T>(callback: (span: AtlanSpan) => T, args?: StartSpanArgs): T;
+/** Braintrust-compatible function wrapper, backed by `observe`. */
+export declare function wrapTraced<F extends AnyFunction>(fn: F, options?: WrapTracedOptions): F;
+/** Common alias used by other tracing SDKs. */
+export declare const traceable: typeof wrapTraced;
+export {};

package/dist/tracing/compat.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Low-friction tracing compatibility helpers.
+ *
+ * The implementation deliberately reuses the SDK's OTel pipeline: ended spans
+ * enter its bounded background batcher, `flush()` drains that same queue, and
+ * third-party OTel instrumentation shares the same provider. There is no
+ * second transport or vendor-specific event format to keep in sync.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceable = exports.Logger = void 0;
+exports.initLogger = initLogger;
+exports.currentLogger = currentLogger;
+exports.currentSpan = currentSpan;
+exports.startSpan = startSpan;
+exports.traced = traced;
+exports.wrapTraced = wrapTraced;
+const client_js_1 = require("./client.js");
+const observe_js_1 = require("./observe.js");
+const LOGGER_SLOT = Symbol.for("atlanai.current-logger.v1");
+function loggerHost() {
+    return globalThis;
+}
+function allSpans(_) {
+    return true;
+}
+function spanArgs(nameOrArgs, options) {
+    if (typeof nameOrArgs === "string")
+        return { name: nameOrArgs, options };
+    const args = nameOrArgs ?? {};
+    const { name = "span", type, event, asType, fields, ...rest } = args;
+    return {
+        name,
+        options: {
+            ...rest,
+            ...(type === undefined && asType === undefined ? {} : { asType: type ?? asType }),
+            ...(event === undefined && fields === undefined ? {} : { fields: event ?? fields }),
+        },
+    };
+}
+/** A small logger facade over one Atlan OTel client. */
+class Logger {
+    client;
+    projectName;
+    asyncFlush;
+    constructor(client, projectName, asyncFlush) {
+        this.client = client;
+        this.projectName = projectName;
+        this.asyncFlush = asyncFlush;
+    }
+    startSpan(nameOrArgs, options = {}) {
+        const resolved = spanArgs(nameOrArgs, options);
+        return this.client.startSpan(resolved.name, resolved.options);
+    }
+    /** Run a callback with an automatically ended, ambient current span. */
+    traced(callback, args = {}) {
+        const resolved = spanArgs(args, {});
+        return this.client.startAsCurrentSpan(resolved.name, resolved.options, callback);
+    }
+    /** Log one complete root event. Delivery is asynchronous by default. */
+    log(event) {
+        const { name = "event", type = "task", ...fields } = event;
+        const span = this.client.startSpan(name, { asType: type, fields });
+        const identity = { traceId: span.traceId, spanId: span.spanId };
+        span.end();
+        if (!this.asyncFlush)
+            void this.client.flush();
+        return identity;
+    }
+    flush() {
+        return this.client.flush();
+    }
+    shutdown() {
+        return this.client.shutdown();
+    }
+}
+exports.Logger = Logger;
+/**
+ * Initialize production tracing with Braintrust-style logger ergonomics.
+ *
+ * All OTel spans are accepted by default and handed to the existing background
+ * batch processor. Initialize this before provider/framework clients so their
+ * instrumentation acquires the same global OTel provider.
+ */
+function initLogger(options = {}) {
+    const { projectName, projectId, serviceName, asyncFlush = true, captureAll = true, setCurrent = true, shouldExportSpan, ...initOptions } = options;
+    const resolvedName = serviceName ?? projectName ?? projectId ?? "global";
+    const exportPredicate = shouldExportSpan ?? (captureAll ? allSpans : undefined);
+    const client = (0, client_js_1.init)({
+        ...initOptions,
+        serviceName: resolvedName,
+        exportMode: asyncFlush ? "batch" : "immediate",
+        ...(exportPredicate === undefined ? {} : { shouldExportSpan: exportPredicate }),
+    });
+    const logger = new Logger(client, resolvedName, asyncFlush);
+    if (setCurrent)
+        loggerHost()[LOGGER_SLOT] = logger;
+    return logger;
+}
+/** The logger most recently initialized with `setCurrent !== false`. */
+function currentLogger() {
+    return loggerHost()[LOGGER_SLOT];
+}
+/** Active span, or a safe no-op span when no traced scope is active. */
+function currentSpan() {
+    return (0, client_js_1.getClient)().currentSpan();
+}
+function startSpan(nameOrArgs, options = {}) {
+    const resolved = spanArgs(nameOrArgs, options);
+    return (0, client_js_1.getClient)().startSpan(resolved.name, resolved.options);
+}
+/** Run a callback in an automatically ended current span. */
+function traced(callback, args = {}) {
+    const resolved = spanArgs(args, {});
+    return (0, client_js_1.getClient)().startAsCurrentSpan(resolved.name, resolved.options, callback);
+}
+/** Braintrust-compatible function wrapper, backed by `observe`. */
+function wrapTraced(fn, options = {}) {
+    const { type, asType, noTraceIO, captureInput, captureOutput, ...rest } = options;
+    return (0, observe_js_1.observe)(fn, {
+        ...rest,
+        ...(type === undefined && asType === undefined ? {} : { asType: type ?? asType }),
+        captureInput: noTraceIO ? false : (captureInput ?? true),
+        captureOutput: noTraceIO ? false : (captureOutput ?? true),
+    });
+}
+/** Common alias used by other tracing SDKs. */
+exports.traceable = wrapTraced;

package/dist/tracing/index.d.ts

@@ -9,6 +9,8 @@
 export { init, getClient, AtlanAI, _resetForTests, type InitOptions, type StartAsCurrentSpanOptions, type StartSpanOptions, type TraceContext, } from "./client.js";
 export { AtlanSpan, noopSpan, resolveSpanType, ROOT_SPAN_CONTEXT_KEY, type ScoreOptions, type UpdateFields, } from "./spans.js";
 export { observe, type ObserveOptions } from "./observe.js";
+export { aiTelemetry, wrapAISDK, type AITelemetryOptions, type AITelemetrySettings, } from "./integrations.js";
+export { Logger, currentLogger, currentSpan, initLogger, startSpan, traceable, traced, wrapTraced, type InitLoggerOptions, type LogEvent, type LoggedSpan, type StartSpanArgs, type WrapTracedOptions, } from "./compat.js";
 export { createSpanId, createSpanIdAsync, createTraceId, createTraceIdAsync } from "./ids.js";
 export { isMessageShaped, serializePayload, toJsonable, truncateUtf8, MAX_DEPTH, TRUNCATION_SUFFIX, } from "./serialize.js";
 export { AtlanConfigError, DEFAULT_BASE_URL, resolveConfig, type ConfigOptions, type Mode, type ResolvedConfig, } from "./config.js";

package/dist/tracing/index.js

@@ -41,7 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.semconv = exports.SDK_VERSION = exports.SDK_LANGUAGE = exports.MaskingSpanExporter = exports.MASK_FAILURE_PLACEHOLDER = exports.applyMask = exports.AtlanSpanProcessor = exports.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES = exports.isKnownInstrumentorSpan = exports.isGenAiSpan = exports.isAtlanSdkSpan = exports.defaultShouldExport = exports.ATLAN_SDK_SCOPE = exports.VisitorIdentifyError = exports.propagateAttributes = exports.resolveConfig = exports.DEFAULT_BASE_URL = exports.AtlanConfigError = exports.TRUNCATION_SUFFIX = exports.MAX_DEPTH = exports.truncateUtf8 = exports.toJsonable = exports.serializePayload = exports.isMessageShaped = exports.createTraceIdAsync = exports.createTraceId = exports.createSpanIdAsync = exports.createSpanId = exports.observe = exports.ROOT_SPAN_CONTEXT_KEY = exports.resolveSpanType = exports.noopSpan = exports.AtlanSpan = exports._resetForTests = exports.AtlanAI = exports.getClient = exports.init = void 0;
+exports.semconv = exports.SDK_VERSION = exports.SDK_LANGUAGE = exports.MaskingSpanExporter = exports.MASK_FAILURE_PLACEHOLDER = exports.applyMask = exports.AtlanSpanProcessor = exports.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES = exports.isKnownInstrumentorSpan = exports.isGenAiSpan = exports.isAtlanSdkSpan = exports.defaultShouldExport = exports.ATLAN_SDK_SCOPE = exports.VisitorIdentifyError = exports.propagateAttributes = exports.resolveConfig = exports.DEFAULT_BASE_URL = exports.AtlanConfigError = exports.TRUNCATION_SUFFIX = exports.MAX_DEPTH = exports.truncateUtf8 = exports.toJsonable = exports.serializePayload = exports.isMessageShaped = exports.createTraceIdAsync = exports.createTraceId = exports.createSpanIdAsync = exports.createSpanId = exports.wrapTraced = exports.traced = exports.traceable = exports.startSpan = exports.initLogger = exports.currentSpan = exports.currentLogger = exports.Logger = exports.wrapAISDK = exports.aiTelemetry = exports.observe = exports.ROOT_SPAN_CONTEXT_KEY = exports.resolveSpanType = exports.noopSpan = exports.AtlanSpan = exports._resetForTests = exports.AtlanAI = exports.getClient = exports.init = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return client_js_1.init; } });
 Object.defineProperty(exports, "getClient", { enumerable: true, get: function () { return client_js_1.getClient; } });
@@ -54,6 +54,18 @@ Object.defineProperty(exports, "resolveSpanType", { enumerable: true, get: funct
 Object.defineProperty(exports, "ROOT_SPAN_CONTEXT_KEY", { enumerable: true, get: function () { return spans_js_1.ROOT_SPAN_CONTEXT_KEY; } });
 var observe_js_1 = require("./observe.js");
 Object.defineProperty(exports, "observe", { enumerable: true, get: function () { return observe_js_1.observe; } });
+var integrations_js_1 = require("./integrations.js");
+Object.defineProperty(exports, "aiTelemetry", { enumerable: true, get: function () { return integrations_js_1.aiTelemetry; } });
+Object.defineProperty(exports, "wrapAISDK", { enumerable: true, get: function () { return integrations_js_1.wrapAISDK; } });
+var compat_js_1 = require("./compat.js");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return compat_js_1.Logger; } });
+Object.defineProperty(exports, "currentLogger", { enumerable: true, get: function () { return compat_js_1.currentLogger; } });
+Object.defineProperty(exports, "currentSpan", { enumerable: true, get: function () { return compat_js_1.currentSpan; } });
+Object.defineProperty(exports, "initLogger", { enumerable: true, get: function () { return compat_js_1.initLogger; } });
+Object.defineProperty(exports, "startSpan", { enumerable: true, get: function () { return compat_js_1.startSpan; } });
+Object.defineProperty(exports, "traceable", { enumerable: true, get: function () { return compat_js_1.traceable; } });
+Object.defineProperty(exports, "traced", { enumerable: true, get: function () { return compat_js_1.traced; } });
+Object.defineProperty(exports, "wrapTraced", { enumerable: true, get: function () { return compat_js_1.wrapTraced; } });
 var ids_js_1 = require("./ids.js");
 Object.defineProperty(exports, "createSpanId", { enumerable: true, get: function () { return ids_js_1.createSpanId; } });
 Object.defineProperty(exports, "createSpanIdAsync", { enumerable: true, get: function () { return ids_js_1.createSpanIdAsync; } });

package/dist/tracing/integrations.d.ts

@@ -0,0 +1,35 @@
+/** Framework integration helpers that reuse the Atlan OpenTelemetry pipeline. */
+import type { Tracer } from "@opentelemetry/api";
+import { type Logger } from "./compat.js";
+export interface AITelemetryOptions {
+    /** Logger whose provider should create framework spans. Defaults to the current logger. */
+    logger?: Pick<Logger, "client">;
+    /** Vercel AI SDK function identifier. */
+    functionId?: string;
+    metadata?: Record<string, unknown>;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+    /** Replace a tracer already present on the call. Defaults to false. */
+    replaceTracer?: boolean;
+}
+export interface AITelemetrySettings {
+    isEnabled: true;
+    tracer: Tracer;
+    functionId?: string;
+    metadata?: Record<string, unknown>;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+}
+/**
+ * Build the native `experimental_telemetry` value used by Vercel AI SDK v3-v6.
+ * No Vercel dependency or vendor wrapper is required.
+ */
+export declare function aiTelemetry(options?: AITelemetryOptions): AITelemetrySettings;
+/**
+ * Braintrust-shaped Vercel AI SDK wrapper.
+ *
+ * Known generation/embedding functions and agent constructors receive native
+ * `experimental_telemetry`; all other exports pass through untouched. The
+ * returned proxy preserves the original namespace's types and lazy getters.
+ */
+export declare function wrapAISDK<T extends object>(sdk: T, options?: AITelemetryOptions): T;

package/dist/tracing/integrations.js

@@ -0,0 +1,95 @@
+"use strict";
+/** Framework integration helpers that reuse the Atlan OpenTelemetry pipeline. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiTelemetry = aiTelemetry;
+exports.wrapAISDK = wrapAISDK;
+const compat_js_1 = require("./compat.js");
+const client_js_1 = require("./client.js");
+/**
+ * Build the native `experimental_telemetry` value used by Vercel AI SDK v3-v6.
+ * No Vercel dependency or vendor wrapper is required.
+ */
+function aiTelemetry(options = {}) {
+    const client = options.logger?.client ?? (0, compat_js_1.currentLogger)()?.client ?? (0, client_js_1.getClient)();
+    return {
+        isEnabled: true,
+        tracer: client.tracerProvider?.getTracer("ai") ?? client.getTracer(),
+        ...(options.functionId === undefined ? {} : { functionId: options.functionId }),
+        ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+        ...(options.recordInputs === undefined ? {} : { recordInputs: options.recordInputs }),
+        ...(options.recordOutputs === undefined ? {} : { recordOutputs: options.recordOutputs }),
+    };
+}
+const AI_SDK_CALLS = new Set([
+    "embed",
+    "embedMany",
+    "generateObject",
+    "generateText",
+    "rerank",
+    "streamObject",
+    "streamText",
+]);
+const AI_SDK_AGENTS = new Set(["Agent", "Experimental_Agent", "ToolLoopAgent"]);
+function withTelemetry(input, options) {
+    const call = typeof input === "object" && input !== null && !Array.isArray(input)
+        ? input
+        : {};
+    const existing = typeof call.experimental_telemetry === "object" && call.experimental_telemetry !== null
+        ? call.experimental_telemetry
+        : {};
+    const generated = aiTelemetry(options);
+    const existingMetadata = typeof existing.metadata === "object" && existing.metadata !== null
+        ? existing.metadata
+        : {};
+    const metadata = { ...(options.metadata ?? {}), ...existingMetadata };
+    const tracer = options.replaceTracer === true || existing.tracer === undefined
+        ? generated.tracer
+        : existing.tracer;
+    return {
+        ...call,
+        experimental_telemetry: {
+            ...generated,
+            ...existing,
+            tracer,
+            ...(Object.keys(metadata).length === 0 ? {} : { metadata }),
+            isEnabled: true,
+        },
+    };
+}
+/**
+ * Braintrust-shaped Vercel AI SDK wrapper.
+ *
+ * Known generation/embedding functions and agent constructors receive native
+ * `experimental_telemetry`; all other exports pass through untouched. The
+ * returned proxy preserves the original namespace's types and lazy getters.
+ */
+function wrapAISDK(sdk, options = {}) {
+    const wrapped = new Map();
+    return new Proxy(sdk, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof property !== "string" ||
+                typeof value !== "function" ||
+                (!AI_SDK_CALLS.has(property) && !AI_SDK_AGENTS.has(property))) {
+                return value;
+            }
+            const cached = wrapped.get(property);
+            if (cached !== undefined)
+                return cached;
+            const proxy = new Proxy(value, {
+                apply(callable, thisArg, argumentsList) {
+                    const args = [...argumentsList];
+                    args[0] = withTelemetry(args[0], options);
+                    return Reflect.apply(callable, thisArg, args);
+                },
+                construct(callable, argumentsList, newTarget) {
+                    const args = [...argumentsList];
+                    args[0] = withTelemetry(args[0], options);
+                    return Reflect.construct(callable, args, newTarget);
+                },
+            });
+            wrapped.set(property, proxy);
+            return proxy;
+        },
+    });
+}

package/dist/tracing/propagation.d.ts

@@ -17,6 +17,7 @@ export interface PropagateAttributesOptions {
     sessionId?: string;
     userId?: string;
     visitorId?: string;
+    experimentId?: string;
     tags?: readonly string[];
     metadata?: Record<string, unknown>;
     traceName?: string;

package/dist/tracing/propagation.js

@@ -56,6 +56,7 @@ const MAX_PROPAGATED_VALUE_CHARS = 200;
 const SESSION_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.session_id");
 const USER_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.user_id");
 const VISITOR_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.visitor_id");
+const EXPERIMENT_ID_KEY = (0, api_1.createContextKey)("atlan.propagated.experiment_id");
 const TAGS_KEY = (0, api_1.createContextKey)("atlan.propagated.tags");
 const METADATA_KEY = (0, api_1.createContextKey)("atlan.propagated.metadata");
 const TRACE_NAME_KEY = (0, api_1.createContextKey)("atlan.propagated.trace_name");
@@ -123,6 +124,9 @@ function propagatedAttributesFromContext(context, includeContent = true) {
     const visitorId = context.getValue(VISITOR_ID_KEY);
     if (typeof visitorId === "string")
         attributes[sc.ATLAN_VISITOR_ID] = visitorId;
+    const experimentId = context.getValue(EXPERIMENT_ID_KEY);
+    if (typeof experimentId === "string")
+        attributes[sc.ATLAN_EVAL_EXPERIMENT_ID] = experimentId;
     const tags = context.getValue(TAGS_KEY);
     if (Array.isArray(tags) && tags.length > 0)
         attributes[sc.ATLAN_TAGS] = [...tags];
@@ -149,6 +153,9 @@ function propagateAttributes(options, fn) {
     const visitorId = validShortString("visitorId", options.visitorId);
     if (visitorId !== undefined)
         context = context.setValue(VISITOR_ID_KEY, visitorId);
+    const experimentId = validShortString("experimentId", options.experimentId);
+    if (experimentId !== undefined)
+        context = context.setValue(EXPERIMENT_ID_KEY, experimentId);
     const newTags = validTags(options.tags);
     if (newTags.length > 0) {
         const existing = context.getValue(TAGS_KEY);

package/dist/tracing/semconv.d.ts

@@ -9,11 +9,19 @@ export type ScoreDataType = (typeof SCORE_DATA_TYPES)[number];
 export declare const ATLAN_COMPLETION_START_TIME = "atlan.completion_start_time";
 export declare const ATLAN_CONSENT_STORE_CONTENT = "atlan.consent.store_content";
 export declare const ATLAN_ENVIRONMENT = "atlan.environment";
+export declare const ATLAN_EVAL_EXPERIMENT_ID = "atlan.eval.experiment_id";
 export declare const ATLAN_INPUT = "atlan.input";
 export declare const ATLAN_INTERNAL_AS_ROOT = "atlan.internal.as_root";
 export declare const ATLAN_OBSERVATION_LEVEL = "atlan.observation.level";
 export declare const ATLAN_OBSERVATION_STATUS_MESSAGE = "atlan.observation.status_message";
 export declare const ATLAN_OUTPUT = "atlan.output";
+export declare const ATLAN_SCORE_COMMENT = "atlan.score.comment";
+export declare const ATLAN_SCORE_DATA_TYPE = "atlan.score.data_type";
+export declare const ATLAN_SCORE_NAME = "atlan.score.name";
+export declare const ATLAN_SCORE_SCORER_ID = "atlan.score.scorer_id";
+export declare const ATLAN_SCORE_SCORER_VERSION = "atlan.score.scorer_version";
+export declare const ATLAN_SCORE_STRING_VALUE = "atlan.score.string_value";
+export declare const ATLAN_SCORE_VALUE = "atlan.score.value";
 export declare const ATLAN_SDK_LANGUAGE = "atlan.sdk.language";
 export declare const ATLAN_SDK_SCHEMA_VERSION = "atlan.sdk.schema_version";
 export declare const ATLAN_SDK_VERSION = "atlan.sdk.version";
@@ -53,6 +61,5 @@ export declare const SPAN_ATTRIBUTE_OWNERS: Readonly<Record<string, string>>;
 export declare const CONTENT_ATTRIBUTES: Readonly<Record<string, readonly string[]>>;
 export declare const PREFIX_ATTRIBUTE_TYPES: Readonly<Record<string, string>>;
 export declare const ATLAN_METADATA_PREFIX = "atlan.metadata.";
-export declare const ATLAN_SCORE_PREFIX = "atlan.score.";
 export declare const EVENT_ATTRIBUTE_TYPES: Readonly<Record<string, Readonly<Record<string, string>>>>;
 export declare const GATEWAY_OWNED_RESOURCE_ATTRIBUTES: readonly ["user.id", "user.email", "org.name"];

package/dist/tracing/semconv.js

@@ -3,8 +3,8 @@
 // Regenerate (from the atlanai-sdk-python repo):
 //   python scripts/gen_semconv.py --lang ts --out <path-to>/src/semconv.ts
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONTENT_ATTRIBUTES = exports.SPAN_ATTRIBUTE_OWNERS = exports.SPAN_ATTRIBUTE_TYPES = exports.RESOURCE_ATTRIBUTE_OWNERS = exports.RESOURCE_ATTRIBUTE_TYPES = exports.USER_ID = exports.USER_EMAIL = exports.SESSION_ID = exports.SERVICE_NAME = exports.ORG_NAME = exports.GEN_AI_USAGE_TOTAL_TOKENS = exports.GEN_AI_USAGE_OUTPUT_TOKENS = exports.GEN_AI_USAGE_OUTPUT_COST = exports.GEN_AI_USAGE_INPUT_TOKENS = exports.GEN_AI_USAGE_INPUT_COST = exports.GEN_AI_USAGE_COST = exports.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = exports.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = exports.GEN_AI_TOOL_TYPE = exports.GEN_AI_TOOL_NAME = exports.GEN_AI_TOOL_CALL_RESULT = exports.GEN_AI_TOOL_CALL_ID = exports.GEN_AI_TOOL_CALL_ARGUMENTS = exports.GEN_AI_SYSTEM_INSTRUCTIONS = exports.GEN_AI_RESPONSE_MODEL = exports.GEN_AI_RESPONSE_ID = exports.GEN_AI_REQUEST_MODEL = exports.GEN_AI_PROVIDER_NAME = exports.GEN_AI_OUTPUT_MESSAGES = exports.GEN_AI_INPUT_MESSAGES = exports.ATLAN_VISITOR_ID = exports.ATLAN_TRACE_NAME = exports.ATLAN_TAGS = exports.ATLAN_SPAN_TYPE = exports.ATLAN_SDK_VERSION = exports.ATLAN_SDK_SCHEMA_VERSION = exports.ATLAN_SDK_LANGUAGE = exports.ATLAN_OUTPUT = exports.ATLAN_OBSERVATION_STATUS_MESSAGE = exports.ATLAN_OBSERVATION_LEVEL = exports.ATLAN_INTERNAL_AS_ROOT = exports.ATLAN_INPUT = exports.ATLAN_ENVIRONMENT = exports.ATLAN_CONSENT_STORE_CONTENT = exports.ATLAN_COMPLETION_START_TIME = exports.SCORE_DATA_TYPES = exports.OBSERVATION_LEVELS = exports.SPAN_TYPE_ALIASES = exports.SPAN_TYPES = exports.SCHEMA_VERSION = void 0;
-exports.GATEWAY_OWNED_RESOURCE_ATTRIBUTES = exports.EVENT_ATTRIBUTE_TYPES = exports.ATLAN_SCORE_PREFIX = exports.ATLAN_METADATA_PREFIX = exports.PREFIX_ATTRIBUTE_TYPES = void 0;
+exports.SERVICE_NAME = exports.ORG_NAME = exports.GEN_AI_USAGE_TOTAL_TOKENS = exports.GEN_AI_USAGE_OUTPUT_TOKENS = exports.GEN_AI_USAGE_OUTPUT_COST = exports.GEN_AI_USAGE_INPUT_TOKENS = exports.GEN_AI_USAGE_INPUT_COST = exports.GEN_AI_USAGE_COST = exports.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = exports.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = exports.GEN_AI_TOOL_TYPE = exports.GEN_AI_TOOL_NAME = exports.GEN_AI_TOOL_CALL_RESULT = exports.GEN_AI_TOOL_CALL_ID = exports.GEN_AI_TOOL_CALL_ARGUMENTS = exports.GEN_AI_SYSTEM_INSTRUCTIONS = exports.GEN_AI_RESPONSE_MODEL = exports.GEN_AI_RESPONSE_ID = exports.GEN_AI_REQUEST_MODEL = exports.GEN_AI_PROVIDER_NAME = exports.GEN_AI_OUTPUT_MESSAGES = exports.GEN_AI_INPUT_MESSAGES = exports.ATLAN_VISITOR_ID = exports.ATLAN_TRACE_NAME = exports.ATLAN_TAGS = exports.ATLAN_SPAN_TYPE = exports.ATLAN_SDK_VERSION = exports.ATLAN_SDK_SCHEMA_VERSION = exports.ATLAN_SDK_LANGUAGE = exports.ATLAN_SCORE_VALUE = exports.ATLAN_SCORE_STRING_VALUE = exports.ATLAN_SCORE_SCORER_VERSION = exports.ATLAN_SCORE_SCORER_ID = exports.ATLAN_SCORE_NAME = exports.ATLAN_SCORE_DATA_TYPE = exports.ATLAN_SCORE_COMMENT = exports.ATLAN_OUTPUT = exports.ATLAN_OBSERVATION_STATUS_MESSAGE = exports.ATLAN_OBSERVATION_LEVEL = exports.ATLAN_INTERNAL_AS_ROOT = exports.ATLAN_INPUT = exports.ATLAN_EVAL_EXPERIMENT_ID = exports.ATLAN_ENVIRONMENT = exports.ATLAN_CONSENT_STORE_CONTENT = exports.ATLAN_COMPLETION_START_TIME = exports.SCORE_DATA_TYPES = exports.OBSERVATION_LEVELS = exports.SPAN_TYPE_ALIASES = exports.SPAN_TYPES = exports.SCHEMA_VERSION = void 0;
+exports.GATEWAY_OWNED_RESOURCE_ATTRIBUTES = exports.EVENT_ATTRIBUTE_TYPES = exports.ATLAN_METADATA_PREFIX = exports.PREFIX_ATTRIBUTE_TYPES = exports.CONTENT_ATTRIBUTES = exports.SPAN_ATTRIBUTE_OWNERS = exports.SPAN_ATTRIBUTE_TYPES = exports.RESOURCE_ATTRIBUTE_OWNERS = exports.RESOURCE_ATTRIBUTE_TYPES = exports.USER_ID = exports.USER_EMAIL = exports.SESSION_ID = void 0;
 exports.SCHEMA_VERSION = "agent-sdk.v1";
 exports.SPAN_TYPES = ["task", "llm", "tool", "function", "score", "session", "turn"];
 exports.SPAN_TYPE_ALIASES = {
@@ -17,11 +17,19 @@ exports.SCORE_DATA_TYPES = ["NUMERIC", "CATEGORICAL", "BOOLEAN"];
 exports.ATLAN_COMPLETION_START_TIME = "atlan.completion_start_time";
 exports.ATLAN_CONSENT_STORE_CONTENT = "atlan.consent.store_content";
 exports.ATLAN_ENVIRONMENT = "atlan.environment";
+exports.ATLAN_EVAL_EXPERIMENT_ID = "atlan.eval.experiment_id";
 exports.ATLAN_INPUT = "atlan.input";
 exports.ATLAN_INTERNAL_AS_ROOT = "atlan.internal.as_root";
 exports.ATLAN_OBSERVATION_LEVEL = "atlan.observation.level";
 exports.ATLAN_OBSERVATION_STATUS_MESSAGE = "atlan.observation.status_message";
 exports.ATLAN_OUTPUT = "atlan.output";
+exports.ATLAN_SCORE_COMMENT = "atlan.score.comment";
+exports.ATLAN_SCORE_DATA_TYPE = "atlan.score.data_type";
+exports.ATLAN_SCORE_NAME = "atlan.score.name";
+exports.ATLAN_SCORE_SCORER_ID = "atlan.score.scorer_id";
+exports.ATLAN_SCORE_SCORER_VERSION = "atlan.score.scorer_version";
+exports.ATLAN_SCORE_STRING_VALUE = "atlan.score.string_value";
+exports.ATLAN_SCORE_VALUE = "atlan.score.value";
 exports.ATLAN_SDK_LANGUAGE = "atlan.sdk.language";
 exports.ATLAN_SDK_SCHEMA_VERSION = "atlan.sdk.schema_version";
 exports.ATLAN_SDK_VERSION = "atlan.sdk.version";
@@ -86,6 +94,14 @@ exports.SPAN_ATTRIBUTE_TYPES = {
     "session.id": "string",
     "user.id": "string",
     "atlan.visitor.id": "string",
+    "atlan.eval.experiment_id": "string",
+    "atlan.score.name": "string",
+    "atlan.score.value": "double",
+    "atlan.score.data_type": "string",
+    "atlan.score.string_value": "string",
+    "atlan.score.comment": "string",
+    "atlan.score.scorer_id": "string",
+    "atlan.score.scorer_version": "int",
     "atlan.tags": "string_list",
     "gen_ai.input.messages": "string",
     "gen_ai.output.messages": "string",
@@ -120,6 +136,14 @@ exports.SPAN_ATTRIBUTE_OWNERS = {
     "session.id": "app",
     "user.id": "app",
     "atlan.visitor.id": "app",
+    "atlan.eval.experiment_id": "app",
+    "atlan.score.name": "app",
+    "atlan.score.value": "app",
+    "atlan.score.data_type": "app",
+    "atlan.score.string_value": "app",
+    "atlan.score.comment": "app",
+    "atlan.score.scorer_id": "app",
+    "atlan.score.scorer_version": "app",
     "atlan.tags": "app",
     "gen_ai.input.messages": "app",
     "gen_ai.output.messages": "app",
@@ -157,20 +181,10 @@ exports.CONTENT_ATTRIBUTES = {
 };
 exports.PREFIX_ATTRIBUTE_TYPES = {
     "atlan.metadata.": "dynamic",
-    "atlan.score.": "double",
 };
 // Prefix constants (trailing dot included).
 exports.ATLAN_METADATA_PREFIX = "atlan.metadata.";
-exports.ATLAN_SCORE_PREFIX = "atlan.score.";
 // Span events and their attribute types.
-exports.EVENT_ATTRIBUTE_TYPES = {
-    "atlan.score": {
-        "atlan.score.name": "string",
-        "atlan.score.value": "double",
-        "atlan.score.data_type": "string",
-        "atlan.score.string_value": "string",
-        "atlan.score.comment": "string",
-    },
-};
+exports.EVENT_ATTRIBUTE_TYPES = {};
 // Reserved for the gateway: the SDK MUST NOT emit these on the resource.
 exports.GATEWAY_OWNED_RESOURCE_ATTRIBUTES = ["user.id", "user.email", "org.name"];

package/dist/tracing/spans.d.ts

@@ -5,7 +5,7 @@
  * attributes. The observation type is set once at creation and immutable.
  * Every method is safe on a non-recording span (no-op posture, SPEC §10.1).
  */
-import { type Span, type TimeInput } from "@opentelemetry/api";
+import { type Span, type TimeInput, type Tracer } from "@opentelemetry/api";
 import type { ResolvedConfig } from "./config.js";
 import { type MaskFunction } from "./masking.js";
 /**
@@ -18,6 +18,10 @@ export interface ScoreOptions {
     dataType?: string;
     stringValue?: string;
     comment?: string;
+    /** Registry scorer artifact cited by the verdict span. */
+    scorerId?: string;
+    /** Positive immutable scorer version ordinal. */
+    scorerVersion?: number;
 }
 export declare function resolveSpanType(asType: string): string;
 export interface UpdateFields {
@@ -42,7 +46,8 @@ export declare class AtlanSpan {
     private readonly otel;
     private readonly config;
     private readonly mask;
-    constructor(otelSpan: Span, config: ResolvedConfig, mask?: MaskFunction);
+    private readonly tracer;
+    constructor(otelSpan: Span, config: ResolvedConfig, mask?: MaskFunction, tracer?: Tracer);
     get otelSpan(): Span;
     get traceId(): string;
     get spanId(): string;
@@ -50,9 +55,10 @@ export declare class AtlanSpan {
     _initialize(asType: string, asRoot: boolean): void;
     private serialize;
     update(fields: UpdateFields): this;
+    /** Braintrust-compatible spelling for incrementally adding span fields. */
+    log(fields: UpdateFields): this;
     /**
-     * Attach a score to this span (SPEC §9.4): an `atlan.score` event plus a
-     * rollup attribute `atlan.score.{name}`.
+     * Emit a dedicated score child span (SPEC §9.4).
      *
      * NUMERIC requires a numeric value; CATEGORICAL requires stringValue
      * (numeric value defaults to 0.0); BOOLEAN encodes value as 0/1.
@@ -67,5 +73,7 @@ export declare class AtlanSpan {
     /** Record an exception and mark the span ERROR (SPEC §9.2). */
     recordFailure(error: unknown): void;
     end(endTime?: TimeInput): void;
+    /** Braintrust-compatible spelling for ending a manually managed span. */
+    close(endTime?: TimeInput): void;
 }
 export declare function noopSpan(config: ResolvedConfig): AtlanSpan;