@atlanai/sdk 0.1.0

package/dist/tracing/semconv.d.ts

@@ -0,0 +1,58 @@
+export declare const SCHEMA_VERSION = "agent-sdk.v1";
+export declare const SPAN_TYPES: readonly ["task", "llm", "tool", "function", "score", "session", "turn"];
+export type SpanType = (typeof SPAN_TYPES)[number];
+export declare const SPAN_TYPE_ALIASES: Readonly<Record<string, string>>;
+export declare const OBSERVATION_LEVELS: readonly ["DEBUG", "DEFAULT", "WARNING", "ERROR"];
+export type ObservationLevel = (typeof OBSERVATION_LEVELS)[number];
+export declare const SCORE_DATA_TYPES: readonly ["NUMERIC", "CATEGORICAL", "BOOLEAN"];
+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_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_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";
+export declare const ATLAN_SPAN_TYPE = "atlan.span.type";
+export declare const ATLAN_TAGS = "atlan.tags";
+export declare const ATLAN_TRACE_NAME = "atlan.trace.name";
+export declare const ATLAN_VISITOR_ID = "atlan.visitor.id";
+export declare const GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages";
+export declare const GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages";
+export declare const GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+export declare const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+export declare const GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+export declare const GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+export declare const GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions";
+export declare const GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments";
+export declare const GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
+export declare const GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result";
+export declare const GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+export declare const GEN_AI_TOOL_TYPE = "gen_ai.tool.type";
+export declare const GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = "gen_ai.usage.cache_creation.input_tokens";
+export declare const GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens";
+export declare const GEN_AI_USAGE_COST = "gen_ai.usage.cost";
+export declare const GEN_AI_USAGE_INPUT_COST = "gen_ai.usage.input_cost";
+export declare const GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+export declare const GEN_AI_USAGE_OUTPUT_COST = "gen_ai.usage.output_cost";
+export declare const GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+export declare const GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens";
+export declare const ORG_NAME = "org.name";
+export declare const SERVICE_NAME = "service.name";
+export declare const SESSION_ID = "session.id";
+export declare const USER_EMAIL = "user.email";
+export declare const USER_ID = "user.id";
+export declare const RESOURCE_ATTRIBUTE_TYPES: Readonly<Record<string, string>>;
+export declare const RESOURCE_ATTRIBUTE_OWNERS: Readonly<Record<string, string>>;
+export declare const SPAN_ATTRIBUTE_TYPES: Readonly<Record<string, string>>;
+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

@@ -0,0 +1,176 @@
+"use strict";
+// Generated from schema/agent-sdk.v1.yaml — DO NOT EDIT.
+// 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.SCHEMA_VERSION = "agent-sdk.v1";
+exports.SPAN_TYPES = ["task", "llm", "tool", "function", "score", "session", "turn"];
+exports.SPAN_TYPE_ALIASES = {
+    "generation": "llm",
+    "span": "task",
+};
+exports.OBSERVATION_LEVELS = ["DEBUG", "DEFAULT", "WARNING", "ERROR"];
+exports.SCORE_DATA_TYPES = ["NUMERIC", "CATEGORICAL", "BOOLEAN"];
+// Attribute name constants (deduped across resource and span registries).
+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_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_SDK_LANGUAGE = "atlan.sdk.language";
+exports.ATLAN_SDK_SCHEMA_VERSION = "atlan.sdk.schema_version";
+exports.ATLAN_SDK_VERSION = "atlan.sdk.version";
+exports.ATLAN_SPAN_TYPE = "atlan.span.type";
+exports.ATLAN_TAGS = "atlan.tags";
+exports.ATLAN_TRACE_NAME = "atlan.trace.name";
+exports.ATLAN_VISITOR_ID = "atlan.visitor.id";
+exports.GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages";
+exports.GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages";
+exports.GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
+exports.GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+exports.GEN_AI_RESPONSE_ID = "gen_ai.response.id";
+exports.GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+exports.GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions";
+exports.GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments";
+exports.GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id";
+exports.GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result";
+exports.GEN_AI_TOOL_NAME = "gen_ai.tool.name";
+exports.GEN_AI_TOOL_TYPE = "gen_ai.tool.type";
+exports.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = "gen_ai.usage.cache_creation.input_tokens";
+exports.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens";
+exports.GEN_AI_USAGE_COST = "gen_ai.usage.cost";
+exports.GEN_AI_USAGE_INPUT_COST = "gen_ai.usage.input_cost";
+exports.GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
+exports.GEN_AI_USAGE_OUTPUT_COST = "gen_ai.usage.output_cost";
+exports.GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+exports.GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens";
+exports.ORG_NAME = "org.name";
+exports.SERVICE_NAME = "service.name";
+exports.SESSION_ID = "session.id";
+exports.USER_EMAIL = "user.email";
+exports.USER_ID = "user.id";
+exports.RESOURCE_ATTRIBUTE_TYPES = {
+    "service.name": "string",
+    "atlan.sdk.schema_version": "string",
+    "atlan.sdk.language": "string",
+    "atlan.sdk.version": "string",
+    "atlan.consent.store_content": "bool",
+    "atlan.environment": "string",
+    "user.id": "string",
+    "user.email": "string",
+    "org.name": "string",
+};
+exports.RESOURCE_ATTRIBUTE_OWNERS = {
+    "service.name": "app",
+    "atlan.sdk.schema_version": "sdk",
+    "atlan.sdk.language": "sdk",
+    "atlan.sdk.version": "sdk",
+    "atlan.consent.store_content": "sdk",
+    "atlan.environment": "app",
+    "user.id": "gateway",
+    "user.email": "gateway",
+    "org.name": "gateway",
+};
+exports.SPAN_ATTRIBUTE_TYPES = {
+    "atlan.span.type": "string",
+    "atlan.trace.name": "string",
+    "atlan.internal.as_root": "bool",
+    "atlan.observation.level": "string",
+    "atlan.observation.status_message": "string",
+    "atlan.completion_start_time": "string",
+    "session.id": "string",
+    "user.id": "string",
+    "atlan.visitor.id": "string",
+    "atlan.tags": "string_list",
+    "gen_ai.input.messages": "string",
+    "gen_ai.output.messages": "string",
+    "gen_ai.system_instructions": "string",
+    "atlan.input": "string",
+    "atlan.output": "string",
+    "gen_ai.request.model": "string",
+    "gen_ai.response.model": "string",
+    "gen_ai.provider.name": "string",
+    "gen_ai.response.id": "string",
+    "gen_ai.usage.input_tokens": "int",
+    "gen_ai.usage.output_tokens": "int",
+    "gen_ai.usage.total_tokens": "int",
+    "gen_ai.usage.cache_read.input_tokens": "int",
+    "gen_ai.usage.cache_creation.input_tokens": "int",
+    "gen_ai.usage.input_cost": "double",
+    "gen_ai.usage.output_cost": "double",
+    "gen_ai.usage.cost": "double",
+    "gen_ai.tool.name": "string",
+    "gen_ai.tool.type": "string",
+    "gen_ai.tool.call.id": "string",
+    "gen_ai.tool.call.arguments": "string",
+    "gen_ai.tool.call.result": "string",
+};
+exports.SPAN_ATTRIBUTE_OWNERS = {
+    "atlan.span.type": "sdk",
+    "atlan.trace.name": "app",
+    "atlan.internal.as_root": "sdk",
+    "atlan.observation.level": "app",
+    "atlan.observation.status_message": "app",
+    "atlan.completion_start_time": "sdk",
+    "session.id": "app",
+    "user.id": "app",
+    "atlan.visitor.id": "app",
+    "atlan.tags": "app",
+    "gen_ai.input.messages": "app",
+    "gen_ai.output.messages": "app",
+    "gen_ai.system_instructions": "app",
+    "atlan.input": "app",
+    "atlan.output": "app",
+    "gen_ai.request.model": "app",
+    "gen_ai.response.model": "app",
+    "gen_ai.provider.name": "app",
+    "gen_ai.response.id": "app",
+    "gen_ai.usage.input_tokens": "app",
+    "gen_ai.usage.output_tokens": "app",
+    "gen_ai.usage.total_tokens": "app",
+    "gen_ai.usage.cache_read.input_tokens": "app",
+    "gen_ai.usage.cache_creation.input_tokens": "app",
+    "gen_ai.usage.input_cost": "app",
+    "gen_ai.usage.output_cost": "app",
+    "gen_ai.usage.cost": "app",
+    "gen_ai.tool.name": "app",
+    "gen_ai.tool.type": "app",
+    "gen_ai.tool.call.id": "app",
+    "gen_ai.tool.call.arguments": "app",
+    "gen_ai.tool.call.result": "app",
+};
+// Consent gate: content-classified attributes, removed when
+// atlan.consent.store_content is false. Prefix entries end with '.'.
+exports.CONTENT_ATTRIBUTES = {
+    "prompts": ["gen_ai.input.messages"],
+    "assistant_responses": ["gen_ai.output.messages"],
+    "system_instructions": ["gen_ai.system_instructions"],
+    "io": ["atlan.input", "atlan.output"],
+    "tool_args": ["gen_ai.tool.call.arguments"],
+    "tool_content": ["gen_ai.tool.call.result"],
+    "metadata": ["atlan.metadata."],
+};
+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",
+    },
+};
+// 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/serialize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Safe serialization + truncation (SPEC §8.3-8.4).
+ *
+ * Never throws: unknown objects degrade to String()/markers, circular
+ * references and excessive depth are cut off with markers, and oversized
+ * payloads are truncated keeping the leading bytes plus an explicit suffix.
+ */
+export declare const MAX_DEPTH = 20;
+export declare const TRUNCATION_SUFFIX = "...[atlan: truncated]";
+export declare function toJsonable(value: unknown, depth?: number, seen?: WeakSet<object>): unknown;
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+/** Serialize an input/output payload to a JSON string (strings pass through). */
+export declare function serializePayload(value: unknown, maxBytes: number): string;
+/**
+ * True for a non-empty array of objects that all carry a "role" key
+ * (SPEC §9.6) — routed to gen_ai.input/output.messages.
+ */
+export declare function isMessageShaped(value: unknown): boolean;

package/dist/tracing/serialize.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Safe serialization + truncation (SPEC §8.3-8.4).
+ *
+ * Never throws: unknown objects degrade to String()/markers, circular
+ * references and excessive depth are cut off with markers, and oversized
+ * payloads are truncated keeping the leading bytes plus an explicit suffix.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRUNCATION_SUFFIX = exports.MAX_DEPTH = void 0;
+exports.toJsonable = toJsonable;
+exports.truncateUtf8 = truncateUtf8;
+exports.serializePayload = serializePayload;
+exports.isMessageShaped = isMessageShaped;
+const logger_js_1 = require("./logger.js");
+exports.MAX_DEPTH = 20;
+exports.TRUNCATION_SUFFIX = "...[atlan: truncated]";
+function bytesToBase64(bytes) {
+    const buffer = globalThis.Buffer;
+    if (buffer)
+        return buffer.from(bytes).toString("base64");
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function toJsonable(value, depth = 0, seen) {
+    if (value === null || value === undefined)
+        return value ?? null;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "bigint") {
+        return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
+            ? Number(value)
+            : value.toString();
+    }
+    if (typeof value === "function")
+        return `<function ${value.name || "anonymous"}>`;
+    if (typeof value === "symbol")
+        return value.toString();
+    if (depth >= exports.MAX_DEPTH)
+        return "<max depth exceeded>";
+    const tracked = seen ?? new WeakSet();
+    const object = value;
+    if (tracked.has(object))
+        return "<circular>";
+    if (object instanceof Uint8Array)
+        return bytesToBase64(object);
+    if (object instanceof ArrayBuffer)
+        return bytesToBase64(new Uint8Array(object));
+    if (object instanceof Date)
+        return object.toISOString();
+    if (object instanceof Error) {
+        return { name: object.name, message: object.message };
+    }
+    const withToJson = object;
+    if (typeof withToJson.toJSON === "function") {
+        try {
+            tracked.add(object);
+            try {
+                return toJsonable(withToJson.toJSON(), depth + 1, tracked);
+            }
+            finally {
+                tracked.delete(object);
+            }
+        }
+        catch {
+            // fall through to the structural walks
+        }
+    }
+    tracked.add(object);
+    try {
+        if (object instanceof Map) {
+            const record = {};
+            for (const [key, item] of object.entries()) {
+                record[String(key)] = toJsonable(item, depth + 1, tracked);
+            }
+            return record;
+        }
+        if (object instanceof Set) {
+            return [...object].map((item) => toJsonable(item, depth + 1, tracked));
+        }
+        if (Array.isArray(object)) {
+            return object.map((item) => toJsonable(item, depth + 1, tracked));
+        }
+        const record = {};
+        for (const [key, item] of Object.entries(object)) {
+            record[key] = toJsonable(item, depth + 1, tracked);
+        }
+        return record;
+    }
+    finally {
+        tracked.delete(object);
+    }
+}
+function truncateUtf8(text, maxBytes) {
+    const encoded = new TextEncoder().encode(text);
+    if (encoded.length <= maxBytes)
+        return text;
+    logger_js_1.logger.warn(`payload of ${encoded.length} bytes exceeds limit ${maxBytes}; truncating`);
+    const head = new TextDecoder("utf-8", { fatal: false }).decode(encoded.subarray(0, maxBytes));
+    // strip a trailing replacement char from a split multi-byte sequence
+    return head.replace(/�+$/, "") + exports.TRUNCATION_SUFFIX;
+}
+/** Serialize an input/output payload to a JSON string (strings pass through). */
+function serializePayload(value, maxBytes) {
+    if (typeof value === "string")
+        return truncateUtf8(value, maxBytes);
+    let rendered;
+    try {
+        rendered = JSON.stringify(toJsonable(value)) ?? "null";
+    }
+    catch {
+        rendered = String(value);
+    }
+    return truncateUtf8(rendered, maxBytes);
+}
+/**
+ * True for a non-empty array of objects that all carry a "role" key
+ * (SPEC §9.6) — routed to gen_ai.input/output.messages.
+ */
+function isMessageShaped(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return false;
+    return value.every((item) => item !== null && typeof item === "object" && !Array.isArray(item) && "role" in item);
+}

package/dist/tracing/span-filter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Export allowlist (SPEC §4).
+ *
+ * A span is exported iff: its instrumentation scope is the SDK's own, OR any
+ * attribute key starts with "gen_ai.", OR its scope matches a known prefix
+ * boundary-aware (scope == p or scope.startsWith(p + ".")).
+ *
+ * The canonical prefix list is mirrored in testdata/conformance/allowlist-v1.json;
+ * tests enforce the two stay identical.
+ */
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+export declare const ATLAN_SDK_SCOPE = "atlan-sdk";
+export declare const KNOWN_INSTRUMENTATION_SCOPE_PREFIXES: readonly string[];
+/** A user-supplied predicate fully replaces the default decision (SPEC §4.3). */
+export type ShouldExportSpan = (span: ReadableSpan) => boolean;
+export declare function isAtlanSdkSpan(span: ReadableSpan): boolean;
+export declare function isGenAiSpan(span: ReadableSpan): boolean;
+export declare function isKnownInstrumentorSpan(span: ReadableSpan): boolean;
+export declare function defaultShouldExport(span: ReadableSpan): boolean;

package/dist/tracing/span-filter.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Export allowlist (SPEC §4).
+ *
+ * A span is exported iff: its instrumentation scope is the SDK's own, OR any
+ * attribute key starts with "gen_ai.", OR its scope matches a known prefix
+ * boundary-aware (scope == p or scope.startsWith(p + ".")).
+ *
+ * The canonical prefix list is mirrored in testdata/conformance/allowlist-v1.json;
+ * tests enforce the two stay identical.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES = exports.ATLAN_SDK_SCOPE = void 0;
+exports.isAtlanSdkSpan = isAtlanSdkSpan;
+exports.isGenAiSpan = isGenAiSpan;
+exports.isKnownInstrumentorSpan = isKnownInstrumentorSpan;
+exports.defaultShouldExport = defaultShouldExport;
+exports.ATLAN_SDK_SCOPE = "atlan-sdk";
+exports.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES = [
+    "agent_framework",
+    "ai",
+    "atlan-sdk",
+    "autogen-core",
+    "haystack",
+    "langfuse-sdk",
+    "langsmith",
+    "litellm",
+    "openinference",
+    "opentelemetry.instrumentation.agno",
+    "opentelemetry.instrumentation.alephalpha",
+    "opentelemetry.instrumentation.anthropic",
+    "opentelemetry.instrumentation.bedrock",
+    "opentelemetry.instrumentation.cohere",
+    "opentelemetry.instrumentation.crewai",
+    "opentelemetry.instrumentation.google_generativeai",
+    "opentelemetry.instrumentation.groq",
+    "opentelemetry.instrumentation.haystack",
+    "opentelemetry.instrumentation.langchain",
+    "opentelemetry.instrumentation.llamaindex",
+    "opentelemetry.instrumentation.mistralai",
+    "opentelemetry.instrumentation.ollama",
+    "opentelemetry.instrumentation.openai",
+    "opentelemetry.instrumentation.openai_agents",
+    "opentelemetry.instrumentation.openai_v2",
+    "opentelemetry.instrumentation.replicate",
+    "opentelemetry.instrumentation.sagemaker",
+    "opentelemetry.instrumentation.together",
+    "opentelemetry.instrumentation.transformers",
+    "opentelemetry.instrumentation.vertexai",
+    "opentelemetry.instrumentation.voyageai",
+    "opentelemetry.instrumentation.watsonx",
+    "opentelemetry.instrumentation.writer",
+    "pydantic-ai",
+    "strands-agents",
+    "vllm",
+];
+function scopeName(span) {
+    return span.instrumentationScope?.name ?? "";
+}
+function isAtlanSdkSpan(span) {
+    return scopeName(span) === exports.ATLAN_SDK_SCOPE;
+}
+function isGenAiSpan(span) {
+    return Object.keys(span.attributes ?? {}).some((key) => key.startsWith("gen_ai."));
+}
+function isKnownInstrumentorSpan(span) {
+    const scope = scopeName(span);
+    if (!scope)
+        return false;
+    return exports.KNOWN_INSTRUMENTATION_SCOPE_PREFIXES.some((prefix) => scope === prefix || scope.startsWith(`${prefix}.`));
+}
+function defaultShouldExport(span) {
+    return isAtlanSdkSpan(span) || isGenAiSpan(span) || isKnownInstrumentorSpan(span);
+}

package/dist/tracing/spans.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AtlanSpan — the ergonomic wrapper over an OTel span (SPEC §9).
+ *
+ * Has-a, not is-a: the wrapper holds the OTel span and writes agent-sdk.v1
+ * 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 { ResolvedConfig } from "./config.js";
+import { type MaskFunction } from "./masking.js";
+/**
+ * Tracks the root AtlanSpan of the currently active trace so scoreTrace() can
+ * target it (SPEC §9.4). Set by client.startAsCurrentSpan.
+ */
+export declare const ROOT_SPAN_CONTEXT_KEY: symbol;
+export interface ScoreOptions {
+    /** "NUMERIC" (default) | "CATEGORICAL" | "BOOLEAN"; unknown values drop the score. */
+    dataType?: string;
+    stringValue?: string;
+    comment?: string;
+}
+export declare function resolveSpanType(asType: string): string;
+export interface UpdateFields {
+    input?: unknown;
+    output?: unknown;
+    metadata?: Record<string, unknown>;
+    tags?: readonly string[];
+    model?: string;
+    responseModel?: string;
+    provider?: string;
+    responseId?: string;
+    usage?: Record<string, unknown>;
+    cost?: Record<string, unknown>;
+    level?: string;
+    statusMessage?: string;
+    toolName?: string;
+    toolCallId?: string;
+    toolArguments?: unknown;
+    toolResult?: unknown;
+}
+export declare class AtlanSpan {
+    private readonly otel;
+    private readonly config;
+    private readonly mask;
+    constructor(otelSpan: Span, config: ResolvedConfig, mask?: MaskFunction);
+    get otelSpan(): Span;
+    get traceId(): string;
+    get spanId(): string;
+    /** @internal */
+    _initialize(asType: string, asRoot: boolean): void;
+    private serialize;
+    update(fields: UpdateFields): this;
+    /**
+     * Attach a score to this span (SPEC §9.4): an `atlan.score` event plus a
+     * rollup attribute `atlan.score.{name}`.
+     *
+     * NUMERIC requires a numeric value; CATEGORICAL requires stringValue
+     * (numeric value defaults to 0.0); BOOLEAN encodes value as 0/1.
+     * Invalid scores are dropped with a warning — never thrown.
+     */
+    score(name: string, value?: unknown, options?: ScoreOptions): void;
+    /**
+     * Attach a score to the current trace's root span when resolvable
+     * in-process, else to this span (SPEC §9.4).
+     */
+    scoreTrace(name: string, value?: unknown, options?: ScoreOptions): void;
+    /** Record an exception and mark the span ERROR (SPEC §9.2). */
+    recordFailure(error: unknown): void;
+    end(endTime?: TimeInput): void;
+}
+export declare function noopSpan(config: ResolvedConfig): AtlanSpan;