@agentmark-ai/shared-utils 0.3.0 → 0.3.2

package/dist/index.d.mts

@@ -71,7 +71,7 @@ type AgentmarkConfig = {
     version: string;
     builtInModels?: string[];
     mcpServers?: McpServers;
-    evals: string[];
+    evals?: string[];
 };
 
 declare function toFrontMatter(content: {
@@ -121,7 +121,8 @@ type PromptFrontmatterV0 = {
 };
 type PromptFrontmatter = PromptFrontmatterV0 | TextPromptFrontmatterV1_0 | ObjectPromptFrontmatterV1_0 | ImagePromptFrontmatterV1_0;
 declare function findPromptFiles(dir: string): Promise<string[]>;
-declare function generateTypeDefinitions(prompts: PromptFrontmatter[]): Promise<string>;
+type GenerateTypesLanguage = "typescript" | "python";
+declare function generateTypeDefinitions(prompts: PromptFrontmatter[], language?: GenerateTypesLanguage): Promise<string>;
 declare function fetchPromptsFrontmatter(options: {
     local?: number;
     rootDir?: string;
@@ -218,6 +219,7 @@ interface NormalizedSpan {
     duration: number;
     name: string;
     kind: string;
+    semanticKind?: string;
     serviceName?: string;
     statusCode: string;
     statusMessage?: string;
@@ -248,6 +250,7 @@ interface NormalizedSpan {
     datasetPath?: string;
     datasetItemName?: string;
     datasetExpectedOutput?: string;
+    datasetInput?: string;
     promptName?: string;
     props?: string;
     commitSha?: string;
@@ -441,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();
@@ -506,6 +530,27 @@ declare class AgentMarkTransformer implements ScopeTransformer {
  */
 declare const AGENTMARK_SCOPE_NAME = "agentmark";
 
+/**
+ * Transformer for the official OTel GenAI Semantic Conventions (v1.37.0+).
+ *
+ * Handles attribute names:
+ *   gen_ai.input.messages   — JSON array of input messages ({role, parts[]})
+ *   gen_ai.output.messages  — JSON array of output messages ({role, parts[], finish_reason})
+ *   gen_ai.system_instructions — JSON array of system instruction parts
+ *
+ * Used by frameworks that follow the official spec:
+ *   - Pydantic AI (scope: "pydantic-ai")
+ *   - Any future OTel-compliant GenAI instrumentation
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+ */
+
+declare class OtelGenAiTransformer implements ScopeTransformer {
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+    static readonly SCOPE_NAME = "pydantic-ai";
+}
+
 declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
 /**
  * Normalize spans from raw OTLP resourceSpans structure
@@ -513,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, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, 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

@@ -71,7 +71,7 @@ type AgentmarkConfig = {
     version: string;
     builtInModels?: string[];
     mcpServers?: McpServers;
-    evals: string[];
+    evals?: string[];
 };
 
 declare function toFrontMatter(content: {
@@ -121,7 +121,8 @@ type PromptFrontmatterV0 = {
 };
 type PromptFrontmatter = PromptFrontmatterV0 | TextPromptFrontmatterV1_0 | ObjectPromptFrontmatterV1_0 | ImagePromptFrontmatterV1_0;
 declare function findPromptFiles(dir: string): Promise<string[]>;
-declare function generateTypeDefinitions(prompts: PromptFrontmatter[]): Promise<string>;
+type GenerateTypesLanguage = "typescript" | "python";
+declare function generateTypeDefinitions(prompts: PromptFrontmatter[], language?: GenerateTypesLanguage): Promise<string>;
 declare function fetchPromptsFrontmatter(options: {
     local?: number;
     rootDir?: string;
@@ -218,6 +219,7 @@ interface NormalizedSpan {
     duration: number;
     name: string;
     kind: string;
+    semanticKind?: string;
     serviceName?: string;
     statusCode: string;
     statusMessage?: string;
@@ -248,6 +250,7 @@ interface NormalizedSpan {
     datasetPath?: string;
     datasetItemName?: string;
     datasetExpectedOutput?: string;
+    datasetInput?: string;
     promptName?: string;
     props?: string;
     commitSha?: string;
@@ -441,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();
@@ -506,6 +530,27 @@ declare class AgentMarkTransformer implements ScopeTransformer {
  */
 declare const AGENTMARK_SCOPE_NAME = "agentmark";
 
+/**
+ * Transformer for the official OTel GenAI Semantic Conventions (v1.37.0+).
+ *
+ * Handles attribute names:
+ *   gen_ai.input.messages   — JSON array of input messages ({role, parts[]})
+ *   gen_ai.output.messages  — JSON array of output messages ({role, parts[], finish_reason})
+ *   gen_ai.system_instructions — JSON array of system instruction parts
+ *
+ * Used by frameworks that follow the official spec:
+ *   - Pydantic AI (scope: "pydantic-ai")
+ *   - Any future OTel-compliant GenAI instrumentation
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+ */
+
+declare class OtelGenAiTransformer implements ScopeTransformer {
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+    static readonly SCOPE_NAME = "pydantic-ai";
+}
+
 declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
 /**
  * Normalize spans from raw OTLP resourceSpans structure
@@ -513,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, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, type OtelEvent, 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 };