@agentmark-ai/shared-utils 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -251,9 +251,11 @@ interface NormalizedSpan {
     datasetItemName?: string;
     datasetExpectedOutput?: string;
     datasetInput?: string;
+    experimentKey?: string;
     promptName?: string;
     props?: string;
     commitSha?: string;
+    sourceTreeHash?: string;
     metadata?: Record<string, string>;
     resourceAttributes: Record<string, any>;
     spanAttributes: Record<string, any>;
@@ -448,7 +450,7 @@ declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefi
 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.
+ * Resolve the semantic kind of a span using a 9-level priority chain.
  *
  * Priority:
  * 1. normalized.semanticKind (from agentmark.span.kind attribute) — if valid
@@ -456,9 +458,11 @@ type SemanticKind = typeof SEMANTIC_KINDS[number];
  * 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
+ * 6. Carries a model (gen_ai.request.model) → llm — vendor-neutral generation
+ *    signal; catches model calls the framework maps above don't name.
+ * 7. Has non-empty ToolCalls → tool
+ * 8. Name-based heuristics
+ * 9. Default → function
  */
 declare function resolveSemanticKind(normalized: Partial<NormalizedSpan> & {
     type: SpanType;
@@ -558,43 +562,4 @@ declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: O
  */
 declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
 
-/**
- * Compute a stable identifier for a dataset row, derived from its input.
- *
- * The identifier survives row reordering, additions, and deletions in the
- * dataset — anything that doesn't change the row's *content* keeps the same
- * id. This is the property regression-vs-baseline comparisons need: the
- * same logical test case in two different runs must produce the same name
- * so the baseline lookup can match them.
- *
- * Format: first 12 hex characters of the MD5 digest of the row's input,
- * canonicalised with sorted keys at every level. This matches the Python
- * runner's implementation byte-for-byte so cross-runtime comparisons
- * (TS-emitted baseline vs. Python-emitted PR run, or vice versa) produce
- * matching identifiers.
- *
- * Falls back to the positional index as a string when the row has no
- * input — in that case there is nothing stable to hash, so positional is
- * the best we can do.
- *
- * Note: we use MD5 here for compatibility with the existing Python
- * implementation. MD5 is not used as a security primitive — it's used as a
- * non-cryptographic content fingerprint, which is its appropriate role.
- */
-declare function computeDatasetItemName(input: unknown, fallbackIndex: number): string;
-/**
- * Stringify a value as canonical JSON with object keys sorted recursively.
- *
- * Differs from `JSON.stringify`:
- * - Object keys are sorted lexicographically at every level of nesting, so
- *   `{a: 1, b: 2}` and `{b: 2, a: 1}` produce the same output.
- * - Non-serializable values (functions, symbols, bigints, undefined) are
- *   coerced to strings via `String(value)`, matching Python's `default=str`
- *   behavior in `json.dumps`.
- *
- * Exported for testing and for callers that need the same canonicalisation
- * for purposes other than item-name hashing.
- */
-declare function canonicalJsonStringify(value: unknown): string;
-
-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, canonicalJsonStringify, computeDatasetItemName, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, resolveSemanticKind, 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

@@ -251,9 +251,11 @@ interface NormalizedSpan {
     datasetItemName?: string;
     datasetExpectedOutput?: string;
     datasetInput?: string;
+    experimentKey?: string;
     promptName?: string;
     props?: string;
     commitSha?: string;
+    sourceTreeHash?: string;
     metadata?: Record<string, string>;
     resourceAttributes: Record<string, any>;
     spanAttributes: Record<string, any>;
@@ -448,7 +450,7 @@ declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefi
 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.
+ * Resolve the semantic kind of a span using a 9-level priority chain.
  *
  * Priority:
  * 1. normalized.semanticKind (from agentmark.span.kind attribute) — if valid
@@ -456,9 +458,11 @@ type SemanticKind = typeof SEMANTIC_KINDS[number];
  * 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
+ * 6. Carries a model (gen_ai.request.model) → llm — vendor-neutral generation
+ *    signal; catches model calls the framework maps above don't name.
+ * 7. Has non-empty ToolCalls → tool
+ * 8. Name-based heuristics
+ * 9. Default → function
  */
 declare function resolveSemanticKind(normalized: Partial<NormalizedSpan> & {
     type: SpanType;
@@ -558,43 +562,4 @@ declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: O
  */
 declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
 
-/**
- * Compute a stable identifier for a dataset row, derived from its input.
- *
- * The identifier survives row reordering, additions, and deletions in the
- * dataset — anything that doesn't change the row's *content* keeps the same
- * id. This is the property regression-vs-baseline comparisons need: the
- * same logical test case in two different runs must produce the same name
- * so the baseline lookup can match them.
- *
- * Format: first 12 hex characters of the MD5 digest of the row's input,
- * canonicalised with sorted keys at every level. This matches the Python
- * runner's implementation byte-for-byte so cross-runtime comparisons
- * (TS-emitted baseline vs. Python-emitted PR run, or vice versa) produce
- * matching identifiers.
- *
- * Falls back to the positional index as a string when the row has no
- * input — in that case there is nothing stable to hash, so positional is
- * the best we can do.
- *
- * Note: we use MD5 here for compatibility with the existing Python
- * implementation. MD5 is not used as a security primitive — it's used as a
- * non-cryptographic content fingerprint, which is its appropriate role.
- */
-declare function computeDatasetItemName(input: unknown, fallbackIndex: number): string;
-/**
- * Stringify a value as canonical JSON with object keys sorted recursively.
- *
- * Differs from `JSON.stringify`:
- * - Object keys are sorted lexicographically at every level of nesting, so
- *   `{a: 1, b: 2}` and `{b: 2, a: 1}` produce the same output.
- * - Non-serializable values (functions, symbols, bigints, undefined) are
- *   coerced to strings via `String(value)`, matching Python's `default=str`
- *   behavior in `json.dumps`.
- *
- * Exported for testing and for callers that need the same canonicalisation
- * for purposes other than item-name hashing.
- */
-declare function canonicalJsonStringify(value: unknown): string;
-
-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, canonicalJsonStringify, computeDatasetItemName, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, normalizeOtlpSpans, normalizeSpan, parseAgentMarkAttributes, parseMetadata, parseTokens, registry, resolveSemanticKind, 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

@@ -40,8 +40,6 @@ __export(index_exports, {
   SpanType: () => SpanType,
   TransformerRegistry: () => TransformerRegistry,
   TypeClassifier: () => TypeClassifier,
-  canonicalJsonStringify: () => canonicalJsonStringify,
-  computeDatasetItemName: () => computeDatasetItemName,
   convertOtlpAttributes: () => convertOtlpAttributes,
   createSignature: () => createSignature,
   detectVersion: () => detectVersion,
@@ -988,39 +986,50 @@ var AiSdkV4Strategy = class {
     return attributes["gen_ai.request.model"] || attributes["ai.model.id"];
   }
   extractInput(attributes) {
-    let messagesValue;
-    if (attributes["ai.prompt.messages"] !== void 0) {
-      messagesValue = attributes["ai.prompt.messages"];
-    } else if (attributes["ai.prompt"] !== void 0) {
-      const promptValue = attributes["ai.prompt"];
-      if (typeof promptValue === "string") {
-        try {
-          const parsed = JSON.parse(promptValue);
-          messagesValue = parsed.messages || parsed;
-        } catch {
-          return void 0;
-        }
-      } else {
-        messagesValue = promptValue.messages || promptValue;
-      }
-    } else {
+    const raw = attributes["ai.prompt.messages"] !== void 0 ? attributes["ai.prompt.messages"] : attributes["ai.prompt"];
+    if (raw === void 0) {
       return void 0;
     }
-    let messages;
-    if (typeof messagesValue === "string") {
+    let value = raw;
+    if (typeof value === "string") {
       try {
-        messages = JSON.parse(messagesValue);
+        value = JSON.parse(value);
       } catch {
-        return void 0;
       }
-    } else {
-      messages = messagesValue;
     }
-    if (!Array.isArray(messages)) {
+    const messages = this.coerceToMessages(value);
+    if (!messages) {
       return void 0;
     }
     return this.normalizeMessages(messages);
   }
+  /**
+   * Coerce the shapes `ai.prompt` / `ai.prompt.messages` can take into a
+   * messages array: a raw array, `{ messages, system? }`,
+   * `{ prompt, system? }` (string prompt), or a bare string.
+   */
+  coerceToMessages(value) {
+    if (typeof value === "string") {
+      return [{ role: "user", content: value }];
+    }
+    if (Array.isArray(value)) {
+      return value;
+    }
+    if (value && typeof value === "object") {
+      if (Array.isArray(value.messages)) {
+        return typeof value.system === "string" ? [{ role: "system", content: value.system }, ...value.messages] : value.messages;
+      }
+      if (typeof value.prompt === "string") {
+        const messages = [];
+        if (typeof value.system === "string") {
+          messages.push({ role: "system", content: value.system });
+        }
+        messages.push({ role: "user", content: value.prompt });
+        return messages;
+      }
+    }
+    return void 0;
+  }
   extractOutput(attributes) {
     if (attributes["ai.result.text"] !== void 0) return attributes["ai.result.text"];
     if (attributes["ai.response.text"] !== void 0) return attributes["ai.response.text"];
@@ -1284,39 +1293,54 @@ var AiSdkV5Strategy = class {
     return attributes["gen_ai.request.model"] || attributes["ai.model.id"];
   }
   extractInput(attributes) {
-    let messagesValue;
-    if (attributes["ai.prompt.messages"] !== void 0) {
-      messagesValue = attributes["ai.prompt.messages"];
-    } else if (attributes["ai.prompt"] !== void 0) {
-      const promptValue = attributes["ai.prompt"];
-      if (typeof promptValue === "string") {
-        try {
-          const parsed = JSON.parse(promptValue);
-          messagesValue = parsed.messages || parsed;
-        } catch {
-          return void 0;
-        }
-      } else {
-        messagesValue = promptValue.messages || promptValue;
-      }
-    } else {
+    const raw = attributes["ai.prompt.messages"] !== void 0 ? attributes["ai.prompt.messages"] : attributes["ai.prompt"];
+    if (raw === void 0) {
       return void 0;
     }
-    let messages;
-    if (typeof messagesValue === "string") {
+    let value = raw;
+    if (typeof value === "string") {
       try {
-        messages = JSON.parse(messagesValue);
+        value = JSON.parse(value);
       } catch {
-        return void 0;
       }
-    } else {
-      messages = messagesValue;
     }
-    if (!Array.isArray(messages)) {
+    const messages = this.coerceToMessages(value);
+    if (!messages) {
       return void 0;
     }
     return this.normalizeMessages(messages);
   }
+  /**
+   * Coerce the shapes `ai.prompt` / `ai.prompt.messages` can take into a
+   * messages array:
+   *   - `[ ...messages ]`              — ai.prompt.messages (leaf spans)
+   *   - `{ messages: [...], system? }` — ai.prompt with messages
+   *   - `{ prompt: "text", system? }`  — ai.prompt for a string prompt
+   *                                      (the parent wrapper spans)
+   *   - `"text"`                       — a bare (non-JSON) prompt string
+   */
+  coerceToMessages(value) {
+    if (typeof value === "string") {
+      return [{ role: "user", content: value }];
+    }
+    if (Array.isArray(value)) {
+      return value;
+    }
+    if (value && typeof value === "object") {
+      if (Array.isArray(value.messages)) {
+        return typeof value.system === "string" ? [{ role: "system", content: value.system }, ...value.messages] : value.messages;
+      }
+      if (typeof value.prompt === "string") {
+        const messages = [];
+        if (typeof value.system === "string") {
+          messages.push({ role: "system", content: value.system });
+        }
+        messages.push({ role: "user", content: value.prompt });
+        return messages;
+      }
+    }
+    return void 0;
+  }
   extractOutput(attributes) {
     if (attributes["ai.response.text"] !== void 0) return attributes["ai.response.text"];
     return void 0;
@@ -1657,6 +1681,8 @@ function parseAgentMarkAttributes(attributes, prefix = "agentmark.") {
   if (get("dataset_expected_output")) result.datasetExpectedOutput = String(get("dataset_expected_output"));
   if (get("dataset_input")) result.datasetInput = String(get("dataset_input"));
   if (get("dataset_path")) result.datasetPath = String(get("dataset_path"));
+  if (get("experiment_key")) result.experimentKey = String(get("experiment_key"));
+  if (get("source_tree_hash")) result.sourceTreeHash = String(get("source_tree_hash"));
   return result;
 }
 
@@ -2171,13 +2197,20 @@ var FRAMEWORK_MAPPINGS = [
   {
     key: "ai.operationId",
     // Vercel AI SDK
+    // The AI SDK emits ai.operationId WITH the "ai." prefix (e.g.
+    // "ai.generateText"); accept both prefixed and unprefixed so generation
+    // wrappers resolve to "llm" instead of falling through to "function".
     map: {
       "embed": "embedding",
       "ai.embed": "embedding",
       "generateText": "llm",
+      "ai.generateText": "llm",
       "streamText": "llm",
+      "ai.streamText": "llm",
       "generateObject": "llm",
-      "streamObject": "llm"
+      "ai.generateObject": "llm",
+      "streamObject": "llm",
+      "ai.streamObject": "llm"
     }
   },
   {
@@ -2221,6 +2254,9 @@ function resolveSemanticKind(normalized, allAttributes) {
   if (normalized.type === "GENERATION" /* GENERATION */) {
     return "llm";
   }
+  if (normalized.model) {
+    return "llm";
+  }
   if (normalized.toolCalls && normalized.toolCalls.length > 0) {
     return "tool";
   }
@@ -2322,36 +2358,6 @@ function normalizeOtlpSpans(resourceSpans) {
   }
   return normalizedSpans;
 }
-
-// src/dataset-item-name.ts
-var import_node_crypto = require("crypto");
-function computeDatasetItemName(input, fallbackIndex) {
-  if (input === void 0 || input === null) {
-    return String(fallbackIndex);
-  }
-  const canonical = canonicalJsonStringify(input);
-  return (0, import_node_crypto.createHash)("md5").update(canonical).digest("hex").slice(0, 12);
-}
-function canonicalJsonStringify(value) {
-  if (value === null) return "null";
-  if (value === void 0) return JSON.stringify(String(void 0));
-  const t = typeof value;
-  if (t === "string" || t === "number" || t === "boolean") {
-    return JSON.stringify(value);
-  }
-  if (t === "bigint" || t === "function" || t === "symbol") {
-    return JSON.stringify(String(value));
-  }
-  if (Array.isArray(value)) {
-    return "[" + value.map(canonicalJsonStringify).join(",") + "]";
-  }
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  const parts = keys.map((k) => {
-    return JSON.stringify(k) + ":" + canonicalJsonStringify(obj[k]);
-  });
-  return "{" + parts.join(",") + "}";
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENTMARK_SCOPE_NAME,
@@ -2364,8 +2370,6 @@ function canonicalJsonStringify(value) {
   SpanType,
   TransformerRegistry,
   TypeClassifier,
-  canonicalJsonStringify,
-  computeDatasetItemName,
   convertOtlpAttributes,
   createSignature,
   detectVersion,