@agentmark-ai/shared-utils 0.6.1 → 0.8.0

package/dist/index.d.mts

@@ -175,6 +175,23 @@ interface ToolCall {
     result?: string;
     providerMetadata?: Record<string, any>;
 }
+/**
+ * A single document returned by a retriever / vector-store search, normalized
+ * from instrumentation that carries documents per-index (OpenInference's
+ * flattened `retrieval.documents.{i}.document.*`) or per-event (OpenLLMetry's
+ * `db.query.result` span events). Stored under a span's `outputObject` as
+ * `{ documents: RetrievalDocument[] }` so the UI can render a ranked panel
+ * (relevance score / distance, content, metadata) instead of a single blob.
+ */
+interface RetrievalDocument {
+    id?: string;
+    content?: string;
+    /** Relevance/similarity score (higher = more relevant). */
+    score?: number;
+    /** Vector distance (lower = closer). Some stores report this instead of a score. */
+    distance?: number;
+    metadata?: Record<string, any>;
+}
 interface OtelScope {
     name?: string;
     version?: string;
@@ -448,9 +465,106 @@ declare function extractCustomMetadata(attributes: Record<string, any>, prefix?:
  */
 declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefix?: string): Partial<NormalizedSpan>;
 
+/**
+ * Shared parser for the "flattened indexed message" attribute shape used by
+ * both OpenInference and OpenLLMetry/Traceloop. Neither emits a single JSON
+ * messages array (the way OTel GenAI v1.37+ does with `gen_ai.input.messages`);
+ * instead they explode each message into one attribute per field, indexed by
+ * position:
+ *
+ *   OpenInference:
+ *     llm.input_messages.0.message.role                 = "user"
+ *     llm.input_messages.0.message.content              = "hello"
+ *     llm.output_messages.0.message.tool_calls.0.tool_call.function.name = "search"
+ *     llm.output_messages.0.message.tool_calls.0.tool_call.function.arguments = "{...}"
+ *
+ *   OpenLLMetry / Traceloop:
+ *     gen_ai.prompt.0.role                              = "user"
+ *     gen_ai.prompt.0.content                           = "hello"
+ *     gen_ai.completion.0.tool_calls.0.name             = "search"
+ *     gen_ai.completion.0.tool_calls.0.arguments        = "{...}"
+ *
+ * The two differ only in path fragments (a `message.` infix, a `tool_call.`
+ * infix, `function.name` vs `name`), so one config-driven parser serves both.
+ */
+interface IndexedMessageConfig {
+    /** Attribute prefix that precedes the integer index, e.g. "llm.input_messages". */
+    prefix: string;
+    /** Path fragment between the index and the per-message fields. OpenInference uses
+     *  "message." (so keys read `…0.message.role`); OpenLLMetry uses "" (`…0.role`). */
+    messageInfix: string;
+    /** Field name for the role. Default "role". */
+    roleKey?: string;
+    /** Field name for scalar text content. Default "content". */
+    contentKey?: string;
+    /** Multi-part content list field (OpenInference `contents`), read when the scalar
+     *  content field is absent. Each part lives at
+     *  `${base}${contentsKey}.${j}.${contentsPartInfix}text`. Omit to disable. */
+    contentsKey?: string;
+    /** Path fragment after the contents index, e.g. "message_content." for OpenInference. */
+    contentsPartInfix?: string;
+    /** Tool-call sub-shape. Omit if the source never carries tool calls. */
+    toolCalls?: {
+        /** Array field name under a message, e.g. "tool_calls". */
+        arrayKey: string;
+        /** Fragment between the tool-call index and its fields. OpenInference uses
+         *  "tool_call." ; OpenLLMetry uses "". */
+        infix: string;
+        /** Relative key to the call id, e.g. "id". */
+        idKey: string;
+        /** Relative key to the tool name. OpenInference "function.name"; OpenLLMetry "name". */
+        nameKey: string;
+        /** Relative key to the JSON-string arguments. OpenInference "function.arguments";
+         *  OpenLLMetry "arguments". */
+        argsKey: string;
+    };
+}
+/**
+ * Collect the distinct, ascending integer indices that appear immediately after
+ * `prefix.` across the attribute keys. Tolerant of gaps and arbitrary key order
+ * (a span may emit message 2 before message 0); we never assume a dense 0..n.
+ * Exported so transformers can reuse it for non-message indexed groups
+ * (e.g. OpenInference `retrieval.documents.{i}.*`).
+ */
+declare function collectIndices(attributes: Record<string, any>, prefix: string): number[];
+/**
+ * Parse the flattened indexed messages under `config.prefix` into normalized
+ * Messages. A message that carries tool calls gets an array content of a text
+ * part (when present) followed by `tool-call` parts, so conversation history is
+ * preserved with full fidelity; a text-only message gets a plain string content.
+ * Returns `undefined` when no messages are present (lets callers fall through to
+ * other extraction paths).
+ */
+declare function parseIndexedMessages(attributes: Record<string, any>, config: IndexedMessageConfig): Message[] | undefined;
+/**
+ * Flatten every tool call across the indexed messages under `config.prefix` into
+ * a span-level ToolCall[]. Used for the response side, where OpenInference and
+ * OpenLLMetry place the assistant's tool calls inside `output_messages` /
+ * `gen_ai.completion` and AgentMark surfaces them as `span.toolCalls`.
+ */
+declare function extractIndexedToolCalls(attributes: Record<string, any>, config: IndexedMessageConfig): ToolCall[] | undefined;
+/**
+ * Collapse normalized messages into a single plain-text string (text parts only,
+ * newline-joined). Tool-call parts are intentionally dropped — they travel
+ * separately via `extractIndexedToolCalls`. Returns `undefined` when there is no
+ * text to show.
+ */
+declare function messagesToPlainText(messages: Message[] | undefined): string | undefined;
+
 /** Valid semantic kind values. */
 declare const SEMANTIC_KINDS: readonly ["function", "llm", "tool", "agent", "retrieval", "embedding", "guardrail"];
 type SemanticKind = typeof SEMANTIC_KINDS[number];
+/**
+ * True when a span looks like a vector-store query: a recognized vector-DB
+ * `db.system`, any `db.vector.query.*` attribute, or `db.query.result` /
+ * `db.search.result` events. Distinguishes a vector search from a plain SQL
+ * query (which carries none of these). Shared by the semantic-kind resolver
+ * (→ classifies as "retrieval") and the dispatching transformer (→ routes to
+ * the OpenLLMetry extractor so the result events become documents).
+ */
+declare function hasVectorStoreSignature(attributes: Record<string, any>, events?: ReadonlyArray<{
+    name: string;
+}>): boolean;
 /**
  * Resolve the semantic kind of a span using a 9-level priority chain.
  *
@@ -557,6 +671,88 @@ declare class OtelGenAiTransformer implements ScopeTransformer {
     static readonly SCOPE_NAME = "pydantic-ai";
 }
 
+/**
+ * Transformer for the OpenInference semantic conventions — the instrumentation
+ * standard maintained by Arize and used by ~30 auto-instrumentors (LangChain,
+ * LlamaIndex, OpenAI Agents SDK, CrewAI, DSPy, Haystack, smolagents, Bedrock,
+ * Anthropic, Google ADK, Instructor, MCP, Guardrails, …). Those instrumentors
+ * each set their own OTel scope name, so this transformer is reached via the
+ * attribute-signature dispatcher rather than a scope registration (see the
+ * DispatchingTransformer).
+ *
+ * Span *classification* (openinference.span.kind → SpanKind) is already handled
+ * by resolveSemanticKind; this transformer fills the gap that left the IO,
+ * model, and token fields empty, because the default OTel-GenAI transformer only
+ * reads `gen_ai.*` keys and OpenInference uses an entirely different shape.
+ *
+ * @see https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md
+ */
+
+/** Join document contents into a readable, searchable text output. */
+declare function retrievalDocumentsToText(documents: RetrievalDocument[]): string | undefined;
+declare class OpenInferenceTransformer implements ScopeTransformer {
+    classify(_span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(_span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
+/**
+ * Transformer for the OpenLLMetry / Traceloop conventions (which OpenLIT also
+ * largely follows). These instrumentors back the AutoGen, Semantic Kernel, and
+ * Agno integrations, among others. Like OpenInference, each emits its own OTel
+ * scope name, so this transformer is reached via the attribute-signature
+ * dispatcher rather than a scope registration.
+ *
+ * Tokens and model already partly resolve through the default OTel-GenAI
+ * transformer's legacy `gen_ai.usage.prompt_tokens` fallbacks; the gap this
+ * closes is the IO, which OpenLLMetry flattens into indexed
+ * `gen_ai.prompt.{i}.*` / `gen_ai.completion.{i}.*` attributes (and, for
+ * workflow/task spans, `traceloop.entity.input/output`) rather than the
+ * `gen_ai.input.messages` JSON array the default transformer expects.
+ *
+ * @see https://www.traceloop.com/docs/openllmetry/privacy/traces
+ */
+
+declare class OpenLLMetryTransformer implements ScopeTransformer {
+    classify(_span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
+/**
+ * Default transformer that routes a span to the right extractor by sniffing its
+ * attribute signature, instead of by OTel scope name.
+ *
+ * The registry dispatches scope → transformer by exact match, which works for
+ * SDKs that emit one stable scope (Vercel AI SDK = "ai", Mastra =
+ * "default-tracer", …). But the OpenInference and OpenLLMetry ecosystems each
+ * span dozens of instrumentor scope names
+ * (`openinference.instrumentation.langchain`,
+ * `@arizeai/openinference-instrumentation-openai`, `opentelemetry.instrumentation.openai`, …),
+ * so per-scope registration doesn't scale. This transformer is registered as the
+ * registry *default* (replacing the bare OTel-GenAI default) and picks the
+ * extractor from unambiguous attribute markers, falling back to the OTel GenAI
+ * semantic conventions when nothing framework-specific is present.
+ *
+ * classify() and transform() must agree on the chosen extractor, so both call
+ * the single `select()` method.
+ */
+
+declare class DispatchingTransformer implements ScopeTransformer {
+    private readonly openInference;
+    private readonly openLLMetry;
+    private readonly otelGenAi;
+    /** Choose the extractor for a span from its attribute/event signature.
+     *  OpenInference is checked before OpenLLMetry because its markers (`llm.*`,
+     *  `openinference.span.kind`) are more specific. Vector-store query spans
+     *  route to the OpenLLMetry extractor — they may carry no `traceloop.*`
+     *  marker (a bare Pinecone span is just `db.system` + `db.query.result`
+     *  events), so without this they'd fall through to the OTel-GenAI catch-all
+     *  and their result documents would be dropped. The bare OTel GenAI
+     *  transformer is the final catch-all. */
+    select(attributes: Record<string, any>, span?: OtelSpan): ScopeTransformer;
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
 declare function normalizeOtlpStatusCode(raw: string | number | undefined | null): string;
 declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
 /**
@@ -565,4 +761,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, 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, normalizeOtlpStatusCode, 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, DispatchingTransformer, type GenerateTypesLanguage, type IndexedMessageConfig, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, OpenInferenceTransformer, OpenLLMetryTransformer, 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 RetrievalDocument, SEMANTIC_KINDS, type ScopeTransformer, type SemanticKind, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, collectIndices, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractIndexedToolCalls, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, hasVectorStoreSignature, messagesToPlainText, normalizeOtlpSpans, normalizeOtlpStatusCode, normalizeSpan, parseAgentMarkAttributes, parseIndexedMessages, parseMetadata, parseTokens, registry, resolveSemanticKind, retrievalDocumentsToText, toFrontMatter, typeClassifier, verifySignature };

package/dist/index.d.ts

@@ -175,6 +175,23 @@ interface ToolCall {
     result?: string;
     providerMetadata?: Record<string, any>;
 }
+/**
+ * A single document returned by a retriever / vector-store search, normalized
+ * from instrumentation that carries documents per-index (OpenInference's
+ * flattened `retrieval.documents.{i}.document.*`) or per-event (OpenLLMetry's
+ * `db.query.result` span events). Stored under a span's `outputObject` as
+ * `{ documents: RetrievalDocument[] }` so the UI can render a ranked panel
+ * (relevance score / distance, content, metadata) instead of a single blob.
+ */
+interface RetrievalDocument {
+    id?: string;
+    content?: string;
+    /** Relevance/similarity score (higher = more relevant). */
+    score?: number;
+    /** Vector distance (lower = closer). Some stores report this instead of a score. */
+    distance?: number;
+    metadata?: Record<string, any>;
+}
 interface OtelScope {
     name?: string;
     version?: string;
@@ -448,9 +465,106 @@ declare function extractCustomMetadata(attributes: Record<string, any>, prefix?:
  */
 declare function parseAgentMarkAttributes(attributes: Record<string, any>, prefix?: string): Partial<NormalizedSpan>;
 
+/**
+ * Shared parser for the "flattened indexed message" attribute shape used by
+ * both OpenInference and OpenLLMetry/Traceloop. Neither emits a single JSON
+ * messages array (the way OTel GenAI v1.37+ does with `gen_ai.input.messages`);
+ * instead they explode each message into one attribute per field, indexed by
+ * position:
+ *
+ *   OpenInference:
+ *     llm.input_messages.0.message.role                 = "user"
+ *     llm.input_messages.0.message.content              = "hello"
+ *     llm.output_messages.0.message.tool_calls.0.tool_call.function.name = "search"
+ *     llm.output_messages.0.message.tool_calls.0.tool_call.function.arguments = "{...}"
+ *
+ *   OpenLLMetry / Traceloop:
+ *     gen_ai.prompt.0.role                              = "user"
+ *     gen_ai.prompt.0.content                           = "hello"
+ *     gen_ai.completion.0.tool_calls.0.name             = "search"
+ *     gen_ai.completion.0.tool_calls.0.arguments        = "{...}"
+ *
+ * The two differ only in path fragments (a `message.` infix, a `tool_call.`
+ * infix, `function.name` vs `name`), so one config-driven parser serves both.
+ */
+interface IndexedMessageConfig {
+    /** Attribute prefix that precedes the integer index, e.g. "llm.input_messages". */
+    prefix: string;
+    /** Path fragment between the index and the per-message fields. OpenInference uses
+     *  "message." (so keys read `…0.message.role`); OpenLLMetry uses "" (`…0.role`). */
+    messageInfix: string;
+    /** Field name for the role. Default "role". */
+    roleKey?: string;
+    /** Field name for scalar text content. Default "content". */
+    contentKey?: string;
+    /** Multi-part content list field (OpenInference `contents`), read when the scalar
+     *  content field is absent. Each part lives at
+     *  `${base}${contentsKey}.${j}.${contentsPartInfix}text`. Omit to disable. */
+    contentsKey?: string;
+    /** Path fragment after the contents index, e.g. "message_content." for OpenInference. */
+    contentsPartInfix?: string;
+    /** Tool-call sub-shape. Omit if the source never carries tool calls. */
+    toolCalls?: {
+        /** Array field name under a message, e.g. "tool_calls". */
+        arrayKey: string;
+        /** Fragment between the tool-call index and its fields. OpenInference uses
+         *  "tool_call." ; OpenLLMetry uses "". */
+        infix: string;
+        /** Relative key to the call id, e.g. "id". */
+        idKey: string;
+        /** Relative key to the tool name. OpenInference "function.name"; OpenLLMetry "name". */
+        nameKey: string;
+        /** Relative key to the JSON-string arguments. OpenInference "function.arguments";
+         *  OpenLLMetry "arguments". */
+        argsKey: string;
+    };
+}
+/**
+ * Collect the distinct, ascending integer indices that appear immediately after
+ * `prefix.` across the attribute keys. Tolerant of gaps and arbitrary key order
+ * (a span may emit message 2 before message 0); we never assume a dense 0..n.
+ * Exported so transformers can reuse it for non-message indexed groups
+ * (e.g. OpenInference `retrieval.documents.{i}.*`).
+ */
+declare function collectIndices(attributes: Record<string, any>, prefix: string): number[];
+/**
+ * Parse the flattened indexed messages under `config.prefix` into normalized
+ * Messages. A message that carries tool calls gets an array content of a text
+ * part (when present) followed by `tool-call` parts, so conversation history is
+ * preserved with full fidelity; a text-only message gets a plain string content.
+ * Returns `undefined` when no messages are present (lets callers fall through to
+ * other extraction paths).
+ */
+declare function parseIndexedMessages(attributes: Record<string, any>, config: IndexedMessageConfig): Message[] | undefined;
+/**
+ * Flatten every tool call across the indexed messages under `config.prefix` into
+ * a span-level ToolCall[]. Used for the response side, where OpenInference and
+ * OpenLLMetry place the assistant's tool calls inside `output_messages` /
+ * `gen_ai.completion` and AgentMark surfaces them as `span.toolCalls`.
+ */
+declare function extractIndexedToolCalls(attributes: Record<string, any>, config: IndexedMessageConfig): ToolCall[] | undefined;
+/**
+ * Collapse normalized messages into a single plain-text string (text parts only,
+ * newline-joined). Tool-call parts are intentionally dropped — they travel
+ * separately via `extractIndexedToolCalls`. Returns `undefined` when there is no
+ * text to show.
+ */
+declare function messagesToPlainText(messages: Message[] | undefined): string | undefined;
+
 /** Valid semantic kind values. */
 declare const SEMANTIC_KINDS: readonly ["function", "llm", "tool", "agent", "retrieval", "embedding", "guardrail"];
 type SemanticKind = typeof SEMANTIC_KINDS[number];
+/**
+ * True when a span looks like a vector-store query: a recognized vector-DB
+ * `db.system`, any `db.vector.query.*` attribute, or `db.query.result` /
+ * `db.search.result` events. Distinguishes a vector search from a plain SQL
+ * query (which carries none of these). Shared by the semantic-kind resolver
+ * (→ classifies as "retrieval") and the dispatching transformer (→ routes to
+ * the OpenLLMetry extractor so the result events become documents).
+ */
+declare function hasVectorStoreSignature(attributes: Record<string, any>, events?: ReadonlyArray<{
+    name: string;
+}>): boolean;
 /**
  * Resolve the semantic kind of a span using a 9-level priority chain.
  *
@@ -557,6 +671,88 @@ declare class OtelGenAiTransformer implements ScopeTransformer {
     static readonly SCOPE_NAME = "pydantic-ai";
 }
 
+/**
+ * Transformer for the OpenInference semantic conventions — the instrumentation
+ * standard maintained by Arize and used by ~30 auto-instrumentors (LangChain,
+ * LlamaIndex, OpenAI Agents SDK, CrewAI, DSPy, Haystack, smolagents, Bedrock,
+ * Anthropic, Google ADK, Instructor, MCP, Guardrails, …). Those instrumentors
+ * each set their own OTel scope name, so this transformer is reached via the
+ * attribute-signature dispatcher rather than a scope registration (see the
+ * DispatchingTransformer).
+ *
+ * Span *classification* (openinference.span.kind → SpanKind) is already handled
+ * by resolveSemanticKind; this transformer fills the gap that left the IO,
+ * model, and token fields empty, because the default OTel-GenAI transformer only
+ * reads `gen_ai.*` keys and OpenInference uses an entirely different shape.
+ *
+ * @see https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md
+ */
+
+/** Join document contents into a readable, searchable text output. */
+declare function retrievalDocumentsToText(documents: RetrievalDocument[]): string | undefined;
+declare class OpenInferenceTransformer implements ScopeTransformer {
+    classify(_span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(_span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
+/**
+ * Transformer for the OpenLLMetry / Traceloop conventions (which OpenLIT also
+ * largely follows). These instrumentors back the AutoGen, Semantic Kernel, and
+ * Agno integrations, among others. Like OpenInference, each emits its own OTel
+ * scope name, so this transformer is reached via the attribute-signature
+ * dispatcher rather than a scope registration.
+ *
+ * Tokens and model already partly resolve through the default OTel-GenAI
+ * transformer's legacy `gen_ai.usage.prompt_tokens` fallbacks; the gap this
+ * closes is the IO, which OpenLLMetry flattens into indexed
+ * `gen_ai.prompt.{i}.*` / `gen_ai.completion.{i}.*` attributes (and, for
+ * workflow/task spans, `traceloop.entity.input/output`) rather than the
+ * `gen_ai.input.messages` JSON array the default transformer expects.
+ *
+ * @see https://www.traceloop.com/docs/openllmetry/privacy/traces
+ */
+
+declare class OpenLLMetryTransformer implements ScopeTransformer {
+    classify(_span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
+/**
+ * Default transformer that routes a span to the right extractor by sniffing its
+ * attribute signature, instead of by OTel scope name.
+ *
+ * The registry dispatches scope → transformer by exact match, which works for
+ * SDKs that emit one stable scope (Vercel AI SDK = "ai", Mastra =
+ * "default-tracer", …). But the OpenInference and OpenLLMetry ecosystems each
+ * span dozens of instrumentor scope names
+ * (`openinference.instrumentation.langchain`,
+ * `@arizeai/openinference-instrumentation-openai`, `opentelemetry.instrumentation.openai`, …),
+ * so per-scope registration doesn't scale. This transformer is registered as the
+ * registry *default* (replacing the bare OTel-GenAI default) and picks the
+ * extractor from unambiguous attribute markers, falling back to the OTel GenAI
+ * semantic conventions when nothing framework-specific is present.
+ *
+ * classify() and transform() must agree on the chosen extractor, so both call
+ * the single `select()` method.
+ */
+
+declare class DispatchingTransformer implements ScopeTransformer {
+    private readonly openInference;
+    private readonly openLLMetry;
+    private readonly otelGenAi;
+    /** Choose the extractor for a span from its attribute/event signature.
+     *  OpenInference is checked before OpenLLMetry because its markers (`llm.*`,
+     *  `openinference.span.kind`) are more specific. Vector-store query spans
+     *  route to the OpenLLMetry extractor — they may carry no `traceloop.*`
+     *  marker (a bare Pinecone span is just `db.system` + `db.query.result`
+     *  events), so without this they'd fall through to the OTel-GenAI catch-all
+     *  and their result documents would be dropped. The bare OTel GenAI
+     *  transformer is the final catch-all. */
+    select(attributes: Record<string, any>, span?: OtelSpan): ScopeTransformer;
+    classify(span: OtelSpan, attributes: Record<string, any>): SpanType;
+    transform(span: OtelSpan, attributes: Record<string, any>): Partial<NormalizedSpan>;
+}
+
 declare function normalizeOtlpStatusCode(raw: string | number | undefined | null): string;
 declare function normalizeSpan(resource: OtelResource, scope: OtelScope, span: OtelSpan): NormalizedSpan;
 /**
@@ -565,4 +761,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, 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, normalizeOtlpStatusCode, 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, DispatchingTransformer, type GenerateTypesLanguage, type IndexedMessageConfig, MastraTransformer, type McpServerConfig, type McpServers, type McpStdioServerConfig, type McpUrlServerConfig, type Message, type ModelSettingsTypeAspectRatio, type ModelSettingsTypeImageSize, type ModelSettingsTypeSelect, type ModelSettingsTypeSlider, type NormalizedSpan, OpenInferenceTransformer, OpenLLMetryTransformer, 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 RetrievalDocument, SEMANTIC_KINDS, type ScopeTransformer, type SemanticKind, SpanType, type StandardMessageContent, type StandardTextContent, type StandardToolCallContent, type StandardToolResultContent, type ToolCall, TransformerRegistry, TypeClassifier, collectIndices, convertOtlpAttributes, createSignature, detectVersion, extractCustomMetadata, extractIndexedToolCalls, extractReasoningFromProviderMetadata, extractResourceScopeSpan, fetchPromptsFrontmatter, findPromptFiles, generateTypeDefinitions, generateUnique8CharString, hasVectorStoreSignature, messagesToPlainText, normalizeOtlpSpans, normalizeOtlpStatusCode, normalizeSpan, parseAgentMarkAttributes, parseIndexedMessages, parseMetadata, parseTokens, registry, resolveSemanticKind, retrievalDocumentsToText, toFrontMatter, typeClassifier, verifySignature };