@agentmark-ai/shared-utils 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,478 @@
+declare const generateUnique8CharString: () => string;
+
+declare function createSignature(secret: string | undefined, payload: string): Promise<string>;
+declare function verifySignature(secret: string, header: string, payload: string): Promise<boolean>;
+
+type Option = {
+    label: string;
+    value: string;
+};
+type ModelSettingsTypeSlider = {
+    minimum: number;
+    maximum: number;
+    default: number;
+    multipleOf: number;
+    type: "slider" | "number";
+    ui?: "slider";
+};
+type ModelSettingsTypeAspectRatio = {
+    type: "string";
+    ui?: "aspectRatio";
+    default: string;
+};
+type ModelSettingsTypeImageSize = {
+    type: "string";
+    ui?: "imageSize";
+    default: string;
+};
+type ModelSettingsTypeSelect = {
+    type: "string";
+    ui?: "select";
+    options: Option[];
+    default: string;
+};
+type AgentmarkModelSettingsConfig = {
+    label: string;
+    order: number;
+    deafult: any;
+} & (ModelSettingsTypeSlider | ModelSettingsTypeSelect | ModelSettingsTypeImageSize | ModelSettingsTypeAspectRatio);
+type AgentmarkModelSettingsSchema = {
+    [key: string]: AgentmarkModelSettingsConfig;
+};
+type AgentmarkModelConfig = {
+    label: string;
+    cost: {
+        inputCost: number;
+        outputCost: number;
+        unitScale: number;
+    };
+    settings: AgentmarkModelSettingsSchema;
+};
+type AgentmarkModelSchema = {
+    [key: string]: AgentmarkModelConfig;
+};
+type McpUrlServerConfig = {
+    url: string;
+    headers?: Record<string, string>;
+};
+type McpStdioServerConfig = {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+};
+type McpServerConfig = McpUrlServerConfig | McpStdioServerConfig;
+type McpServers = Record<string, McpServerConfig>;
+type AgentmarkConfig = {
+    $schema?: string;
+    mdxVersion?: "1.0" | "0.0";
+    agentmarkPath: string;
+    modelSchemas?: AgentmarkModelSchema;
+    version: string;
+    builtInModels?: string[];
+    mcpServers?: McpServers;
+    evals: string[];
+};
+
+declare function toFrontMatter(content: {
+    [key: string]: any;
+}): string;
+
+type TextPromptFrontmatterV1_0 = {
+    path: string;
+    version: "1.0";
+    text_config: {
+        model_name: string;
+        tools?: string[];
+    };
+    input_schema?: any;
+};
+type ObjectPromptFrontmatterV1_0 = {
+    path: string;
+    version: "1.0";
+    object_config: {
+        model_name: string;
+        schema: any;
+        tools?: Record<string, any>;
+    };
+    input_schema?: any;
+};
+type ImagePromptFrontmatterV1_0 = {
+    path: string;
+    version: "1.0";
+    image_config: {
+        model_name: string;
+        tools?: Record<string, any>;
+    };
+    input_schema?: any;
+};
+type PromptFrontmatterV0 = {
+    path: string;
+    metadata: {
+        model?: {
+            settings?: {
+                schema?: any;
+                tools?: Record<string, any>;
+            };
+        };
+    };
+    input_schema?: any;
+    version?: "0.0";
+};
+type PromptFrontmatter = PromptFrontmatterV0 | TextPromptFrontmatterV1_0 | ObjectPromptFrontmatterV1_0 | ImagePromptFrontmatterV1_0;
+declare function findPromptFiles(dir: string): Promise<string[]>;
+declare function generateTypeDefinitions(prompts: PromptFrontmatter[]): Promise<string>;
+declare function fetchPromptsFrontmatter(options: {
+    local?: number;
+    rootDir?: string;
+}): Promise<PromptFrontmatter[]>;
+
+declare enum SpanType {
+    SPAN = "SPAN",
+    GENERATION = "GENERATION",
+    EVENT = "EVENT"
+}
+/**
+ * Standard message content part types
+ */
+interface StandardTextContent {
+    type: 'text';
+    text: string;
+}
+interface StandardToolCallContent {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, any>;
+}
+interface StandardToolResultContent {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    result: any;
+}
+type StandardMessageContent = StandardTextContent | StandardToolCallContent | StandardToolResultContent | string;
+/**
+ * Standard message type used throughout the normalizer.
+ * Messages are normalized from V4/V5 formats to this standard format.
+ *
+ * Content can be:
+ * - A plain string
+ * - An array of content parts (text, tool-call, tool-result)
+ */
+interface Message {
+    role: string;
+    content: StandardMessageContent | StandardMessageContent[];
+}
+interface ToolCall {
+    type: string;
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, any>;
+    result?: string;
+    providerMetadata?: Record<string, any>;
+}
+interface OtelScope {
+    name?: string;
+    version?: string;
+}
+interface OtelResource {
+    attributes?: Record<string, any>;
+}
+interface OtelEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes?: Record<string, any>;
+}
+interface OtelLink {
+    traceId: string;
+    spanId: string;
+    traceState?: string;
+    attributes?: Record<string, any>;
+}
+interface OtelSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceState?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: Record<string, any>;
+    events?: OtelEvent[];
+    links?: OtelLink[];
+    status?: {
+        code: number;
+        message?: string;
+    };
+}
+interface NormalizedSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceState?: string;
+    type: SpanType;
+    startTime: number;
+    endTime?: number;
+    duration: number;
+    name: string;
+    kind: string;
+    serviceName?: string;
+    statusCode: string;
+    statusMessage?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    cost?: number;
+    input?: Message[];
+    output?: string;
+    outputObject?: Record<string, any>;
+    toolCalls?: ToolCall[];
+    finishReason?: string;
+    settings?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        presencePenalty?: number;
+        frequencyPenalty?: number;
+    };
+    sessionId?: string;
+    sessionName?: string;
+    userId?: string;
+    traceName?: string;
+    datasetRunId?: string;
+    datasetRunName?: string;
+    datasetPath?: string;
+    datasetItemName?: string;
+    datasetExpectedOutput?: string;
+    promptName?: string;
+    props?: string;
+    commitSha?: string;
+    metadata?: Record<string, string>;
+    resourceAttributes: Record<string, any>;
+    spanAttributes: Record<string, any>;
+    events: Array<{
+        timestamp: number;
+        name: string;
+        attributes: Record<string, any>;
+    }>;
+    links: Array<{
+        traceId: string;
+        spanId: string;
+        traceState?: string;
+        attributes?: Record<string, any>;
+    }>;
+}
+interface AttributeExtractor {
+    extractModel(attributes: Record<string, any>): string | undefined;
+    extractInput(attributes: Record<string, any>): Message[] | undefined;
+    extractOutput(attributes: Record<string, any>): string | undefined;
+    extractTokens(attributes: Record<string, any>): {
+        input?: number;
+        output?: number;
+        total?: number;
+        reasoning?: number;
+    };
+    extractMetadata(attributes: Record<string, any>): Partial<NormalizedSpan>;
+    extractToolCalls(attributes: Record<string, any>): ToolCall[] | undefined;
+    extractOutputObject(attributes: Record<string, any>): Record<string, any> | undefined;
+    extractFinishReason(attributes: Record<string, any>): string | undefined;
+    extractSettings(attributes: Record<string, any>): NormalizedSpan['settings'];
+}
+interface ScopeTransformer {
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
+/**
+ * OTLP attribute value types
+ */
+interface OtlpAttributeValue {
+    stringValue?: string;
+    intValue?: string | number;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values?: OtlpAttributeValue[];
+    };
+    bytesValue?: string | Uint8Array;
+}
+/**
+ * OTLP attribute structure
+ */
+interface OtlpAttribute {
+    key: string;
+    value: OtlpAttributeValue;
+}
+/**
+ * Raw OTLP span structure
+ */
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceState?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: OtlpAttribute[];
+    events?: OtlpEvent[];
+    links?: OtlpLink[];
+    status?: {
+        code: number;
+        message?: string;
+    };
+    droppedAttributesCount?: number;
+    droppedEventsCount?: number;
+    droppedLinksCount?: number;
+}
+/**
+ * Raw OTLP event structure
+ */
+interface OtlpEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes?: OtlpAttribute[];
+    droppedAttributesCount?: number;
+}
+/**
+ * Raw OTLP link structure
+ */
+interface OtlpLink {
+    traceId: string;
+    spanId: string;
+    traceState?: string;
+    attributes?: OtlpAttribute[];
+    droppedAttributesCount?: number;
+}
+/**
+ * Raw OTLP resource structure
+ */
+interface OtlpResource {
+    attributes?: OtlpAttribute[];
+    droppedAttributesCount?: number;
+}
+/**
+ * Raw OTLP scope structure
+ */
+interface OtlpScope {
+    name?: string;
+    version?: string;
+}
+/**
+ * Raw OTLP scope spans structure
+ */
+interface OtlpScopeSpans {
+    scope?: OtlpScope;
+    spans: OtlpSpan[];
+}
+/**
+ * Raw OTLP resource spans structure
+ */
+interface OtlpResourceSpans {
+    resource?: OtlpResource;
+    scopeSpans: OtlpScopeSpans[];
+}
+/**
+ * Convert OTLP attribute array to flat Record<string, any>
+ */
+declare function convertOtlpAttributes(attributes?: OtlpAttribute[]): Record<string, any>;
+/**
+ * Extract resource, scope, and span from OTLP structure
+ */
+declare function extractResourceScopeSpan(resourceSpans: OtlpResourceSpans): Array<{
+    resource: OtelResource;
+    scope: OtelScope;
+    span: OtelSpan;
+}>;
+
+declare class TransformerRegistry {
+    private transformers;
+    private defaultTransformer;
+    register(scope: string, transformer: ScopeTransformer): void;
+    setDefault(transformer: ScopeTransformer): void;
+    getTransformer(scope: string): ScopeTransformer | null;
+}
+declare const registry: TransformerRegistry;
+
+declare class TypeClassifier {
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+}
+declare const typeClassifier: TypeClassifier;
+
+interface TokenKeys {
+    inputKey?: string;
+    outputKey?: string;
+    totalKey?: string;
+    promptKey?: string;
+    completionKey?: string;
+    reasoningKey?: string;
+}
+interface TokenCounts {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+}
+declare function parseTokens(attributes: Record<string, any>, keys: TokenKeys): TokenCounts;
+
+declare function parseMetadata(attributes: Record<string, any>, prefix?: string): Partial<NormalizedSpan>;
+/**
+ * Extracts custom metadata keys from attributes that start with the given prefix.
+ * Excludes known metadata fields that are already extracted as normalized fields.
+ *
+ * @param attributes - The attributes to extract from
+ * @param prefix - The prefix to look for (default: 'agentmark.metadata.')
+ * @returns A record of custom metadata keys (with prefix stripped) to string values
+ */
+declare function extractCustomMetadata(attributes: Record<string, any>, prefix?: string): Record<string, string>;
+
+/**
+ * Parse attributes with 'agentmark.' prefix (not 'agentmark.metadata.')
+ * These are direct context attributes set by the AgentMark SDK.
+ *
+ * @param attributes - The attributes to extract from
+ * @param prefix - The prefix to look for (default: 'agentmark.')
+ * @returns Partial NormalizedSpan with extracted fields in camelCase
+ */
+declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefix?: string): Partial<NormalizedSpan>;
+
+declare class AiSdkTransformer implements ScopeTransformer {
+    private strategies;
+    constructor();
+    classify(span: OtelSpan, _attributes: Record<string, any>): SpanType;
+    transform(_span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
+/**
+ * AI SDK-specific token extraction helpers
+ */
+/**
+ * Extracts reasoning tokens from AI SDK's providerMetadata attribute.
+ * This is a fallback when ai.usage.reasoningTokens is not directly available.
+ */
+declare function extractReasoningFromProviderMetadata(attributes: Record<string, any>): number | undefined;
+
+type AiSdkVersion = 'v5' | 'v4' | 'unknown';
+declare function detectVersion(attributes: Record<string, any>): AiSdkVersion;
+
+declare class MastraTransformer implements ScopeTransformer {
+    classify(span: OtelSpan, _attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+    private extractModelConfig;
+    private extractInput;
+    private extractStreamResult;
+}
+
+declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
+/**
+ * Normalize spans from raw OTLP resourceSpans structure
+ * This is a higher-level API that accepts raw OTLP format and handles conversion internally
+ */
+declare function normalizeOtlpSpans(resourceSpans: OtlpResourceSpans[]): NormalizedSpan[];
+
+export { type AgentmarkConfig, type AgentmarkModelConfig, type AgentmarkModelSchema, type AgentmarkModelSettingsConfig, type AgentmarkModelSettingsSchema, AiSdkTransformer, type AiSdkVersion, type AttributeExtractor, 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 };