@agentmark-ai/shared-utils 0.3.1 → 0.3.2

package/dist/index.d.mts

@@ -219,6 +219,7 @@ interface NormalizedSpan {
     duration: number;
     name: string;
     kind: string;
+    semanticKind?: string;
     serviceName?: string;
     statusCode: string;
     statusMessage?: string;
@@ -443,6 +444,27 @@ declare function extractCustomMetadata(attributes: Record<string, any>, prefix?:
  */
 declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefix?: string): Partial<NormalizedSpan>;
 
+/** Valid semantic kind values. */
+declare const SEMANTIC_KINDS: readonly ["function", "llm", "tool", "agent", "retrieval", "embedding", "guardrail"];
+type SemanticKind = typeof SEMANTIC_KINDS[number];
+/**
+ * Resolve the semantic kind of a span using an 8-level priority chain.
+ *
+ * Priority:
+ * 1. normalized.semanticKind (from agentmark.span.kind attribute) — if valid
+ * 2. openinference.span.kind attribute
+ * 3. Framework-specific attributes (Vercel AI SDK, Traceloop, LangChain, Genkit)
+ * 4. gen_ai.operation.name → llm/embedding
+ * 5. Type = GENERATION → llm
+ * 6. Has non-empty ToolCalls → tool
+ * 7. Name-based heuristics
+ * 8. Default → function
+ */
+declare function resolveSemanticKind(normalized: Partial<NormalizedSpan> & {
+    type: SpanType;
+    name: string;
+}, allAttributes: Record<string, any>): SemanticKind;
+
 declare class AiSdkTransformer implements ScopeTransformer {
     private strategies;
     constructor();
@@ -536,4 +558,4 @@ declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: O
  */
 declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
 
-export { AGENTMARK_SCOPE_NAME, AgentMarkTransformer, type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, AgentMarkTransformer as ClaudeAgentTransformer, type GenerateTypesLanguage, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, OtelGenAiTransformer, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, type ScopeTransformer, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, toFrontMatter, typeClassifier, verifySignature };
+export { AGENTMARK_SCOPE_NAME, AgentMarkTransformer, type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, AgentMarkTransformer as ClaudeAgentTransformer, type GenerateTypesLanguage, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, OtelGenAiTransformer, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, SEMANTIC_KINDS, type ScopeTransformer, type SemanticKind, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, resolveSemanticKind, toFrontMatter, typeClassifier, verifySignature };

package/dist/index.d.ts

@@ -219,6 +219,7 @@ interface NormalizedSpan {
     duration: number;
     name: string;
     kind: string;
+    semanticKind?: string;
     serviceName?: string;
     statusCode: string;
     statusMessage?: string;
@@ -443,6 +444,27 @@ declare function extractCustomMetadata(attributes: Record<string, any>, prefix?:
  */
 declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefix?: string): Partial<NormalizedSpan>;
 
+/** Valid semantic kind values. */
+declare const SEMANTIC_KINDS: readonly ["function", "llm", "tool", "agent", "retrieval", "embedding", "guardrail"];
+type SemanticKind = typeof SEMANTIC_KINDS[number];
+/**
+ * Resolve the semantic kind of a span using an 8-level priority chain.
+ *
+ * Priority:
+ * 1. normalized.semanticKind (from agentmark.span.kind attribute) — if valid
+ * 2. openinference.span.kind attribute
+ * 3. Framework-specific attributes (Vercel AI SDK, Traceloop, LangChain, Genkit)
+ * 4. gen_ai.operation.name → llm/embedding
+ * 5. Type = GENERATION → llm
+ * 6. Has non-empty ToolCalls → tool
+ * 7. Name-based heuristics
+ * 8. Default → function
+ */
+declare function resolveSemanticKind(normalized: Partial<NormalizedSpan> & {
+    type: SpanType;
+    name: string;
+}, allAttributes: Record<string, any>): SemanticKind;
+
 declare class AiSdkTransformer implements ScopeTransformer {
     private strategies;
     constructor();
@@ -536,4 +558,4 @@ declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: O
  */
 declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
 
-export { AGENTMARK_SCOPE_NAME, AgentMarkTransformer, type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, AgentMarkTransformer as ClaudeAgentTransformer, type GenerateTypesLanguage, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, OtelGenAiTransformer, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, type ScopeTransformer, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, toFrontMatter, typeClassifier, verifySignature };
+export { AGENTMARK_SCOPE_NAME, AgentMarkTransformer, type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, AgentMarkTransformer as ClaudeAgentTransformer, type GenerateTypesLanguage, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, OtelGenAiTransformer, type OtelLink, type OtelResource, type OtelScope, type OtelSpan, type OtlpAttribute, type OtlpAttributeValue, type OtlpEvent, type OtlpLink, type OtlpResource, type OtlpResourceSpans, type OtlpScope, type OtlpScopeSpans, type OtlpSpan, SEMANTIC_KINDS, type ScopeTransformer, type SemanticKind, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, resolveSemanticKind, toFrontMatter, typeClassifier, verifySignature };

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   ClaudeAgentTransformer: () => AgentMarkTransformer,
   MastraTransformer: () => MastraTransformer,
   OtelGenAiTransformer: () => OtelGenAiTransformer,
+  SEMANTIC_KINDS: () => SEMANTIC_KINDS,
   SpanType: () => SpanType,
   TransformerRegistry: () => TransformerRegistry,
   TypeClassifier: () => TypeClassifier,
@@ -55,6 +56,7 @@ __export(index_exports, {
   parseMetadata: () => parseMetadata,
   parseTokens: () => parseTokens,
   registry: () => registry,
+  resolveSemanticKind: () => resolveSemanticKind,
   toFrontMatter: () => toFrontMatter,
   typeClassifier: () => typeClassifier,
   verifySignature: () => verifySignature
@@ -889,8 +891,7 @@ var KNOWN_METADATA_FIELDS = /* @__PURE__ */ new Set([
   "dataset_expected_output",
   "dataset_input",
   "prompt_name",
-  "props",
-  "commit_sha"
+  "props"
 ]);
 function parseMetadata(attributes, prefix = "agentmark.metadata.") {
   const result = {};
@@ -1675,7 +1676,7 @@ function parseAgentMarkAttributes(attributes, prefix = "agentmark.") {
   if (get("trace_name")) result.traceName = String(get("trace_name"));
   if (get("prompt_name")) result.promptName = String(get("prompt_name"));
   if (get("props")) result.props = String(get("props"));
-  if (get("span.kind")) result.kind = String(get("span.kind"));
+  if (get("span.kind")) result.semanticKind = String(get("span.kind"));
   if (get("dataset_run_id")) result.datasetRunId = String(get("dataset_run_id"));
   if (get("dataset_run_name")) result.datasetRunName = String(get("dataset_run_name"));
   if (get("dataset_item_name")) result.datasetItemName = String(get("dataset_item_name"));
@@ -1745,6 +1746,9 @@ var AgentMarkTransformer = class {
     if (operationName === OperationNames.CHAT || operationName === OperationNames.TEXT_COMPLETION) {
       return "GENERATION" /* GENERATION */;
     }
+    if (operationName === OperationNames.EMBEDDINGS) {
+      return "GENERATION" /* GENERATION */;
+    }
     if (span.name === SpanNames.CHAT || span.name.startsWith(SpanNames.CHAT + " ")) {
       return "GENERATION" /* GENERATION */;
     }
@@ -2167,6 +2171,83 @@ function extractResourceScopeSpan(resourceSpans) {
   return result;
 }
 
+// src/normalizer/resolvers/semantic-kind-resolver.ts
+var SEMANTIC_KINDS = ["function", "llm", "tool", "agent", "retrieval", "embedding", "guardrail"];
+var VALID_KINDS = new Set(SEMANTIC_KINDS);
+var OPENINFERENCE_MAP = {
+  "CHAIN": "function",
+  "LLM": "llm",
+  "TOOL": "tool",
+  "AGENT": "agent",
+  "RETRIEVER": "retrieval",
+  "EMBEDDING": "embedding",
+  "GUARDRAIL": "guardrail",
+  "RERANKER": "retrieval"
+};
+var FRAMEWORK_MAPPINGS = [
+  {
+    key: "ai.operationId",
+    // Vercel AI SDK
+    map: {
+      "embed": "embedding",
+      "ai.embed": "embedding",
+      "generateText": "llm",
+      "streamText": "llm",
+      "generateObject": "llm",
+      "streamObject": "llm"
+    }
+  },
+  {
+    key: "traceloop.span.kind",
+    // Traceloop / OpenLLMetry
+    map: { "LLM": "llm", "TOOL": "tool", "AGENT": "agent", "WORKFLOW": "function", "TASK": "function" }
+  },
+  {
+    key: "langchain.run_type",
+    // LangChain via OTLP
+    map: { "llm": "llm", "chat_model": "llm", "retriever": "retrieval", "tool": "tool", "chain": "function", "embedding": "embedding" }
+  },
+  {
+    key: "genkit:type",
+    // Firebase Genkit
+    map: { "model": "llm", "tool": "tool", "flow": "function", "retriever": "retrieval", "embedder": "embedding" }
+  }
+];
+function resolveSemanticKind(normalized, allAttributes) {
+  if (normalized.semanticKind && VALID_KINDS.has(normalized.semanticKind)) {
+    return normalized.semanticKind;
+  }
+  const oiKind = allAttributes["openinference.span.kind"];
+  if (oiKind) {
+    const mapped = OPENINFERENCE_MAP[String(oiKind).toUpperCase()];
+    if (mapped) return mapped;
+  }
+  for (const { key, map } of FRAMEWORK_MAPPINGS) {
+    const val = allAttributes[key];
+    if (val) {
+      const mapped = map[String(val)];
+      if (mapped) return mapped;
+    }
+  }
+  const opName = allAttributes["gen_ai.operation.name"];
+  if (opName) {
+    const op = String(opName).toLowerCase();
+    if (op === "chat" || op === "text_completion" || op === "generate_content") return "llm";
+    if (op === "embeddings") return "embedding";
+  }
+  if (normalized.type === "GENERATION" /* GENERATION */) {
+    return "llm";
+  }
+  if (normalized.toolCalls && normalized.toolCalls.length > 0) {
+    return "tool";
+  }
+  const name = (normalized.name || "").toLowerCase();
+  if (/retriev|search|rag/i.test(name)) return "retrieval";
+  if (/embed/i.test(name)) return "embedding";
+  if (/guard|safety/i.test(name)) return "guardrail";
+  return "function";
+}
+
 // src/normalizer/type-classifier.ts
 var TypeClassifier = class {
   classify(span, attributes) {
@@ -2245,6 +2326,7 @@ function normalizeSpan(resource, scope, span) {
   }
   const agentMarkAttributes = parseAgentMarkAttributes(allAttributes);
   Object.assign(normalized, agentMarkAttributes);
+  normalized.semanticKind = resolveSemanticKind(normalized, allAttributes);
   return normalized;
 }
 function normalizeOtlpSpans(resourceSpans) {
@@ -2265,6 +2347,7 @@ function normalizeOtlpSpans(resourceSpans) {
   ClaudeAgentTransformer,
   MastraTransformer,
   OtelGenAiTransformer,
+  SEMANTIC_KINDS,
   SpanType,
   TransformerRegistry,
   TypeClassifier,
@@ -2284,6 +2367,7 @@ function normalizeOtlpSpans(resourceSpans) {
   parseMetadata,
   parseTokens,
   registry,
+  resolveSemanticKind,
   toFrontMatter,
   typeClassifier,
   verifySignature