/**
 * Builders for the OpenTelemetry GenAI semantic conventions.
 *
 * Translates LiveKit's own types — {@link ChatContext}, {@link FunctionCall}, tool
 * definitions, token usage — into the shapes the GenAI semantic conventions define, so a span
 * LiveKit produces is understood by any backend that speaks the convention (Datadog Agent
 * Observability, Langfuse, Braintrust, an OTLP collector) without a LiveKit-specific mapping.
 *
 * Message content follows the `gen_ai.input.messages` / `gen_ai.output.messages` /
 * `gen_ai.system_instructions` JSON schemas from
 * https://github.com/open-telemetry/semantic-conventions-genai. OpenTelemetry attributes
 * cannot hold structured values, so the convention's fallback applies and each value is
 * recorded as a JSON string.
 *
 * Content capture is on by default, matching the `lk.pii.*` content LiveKit already records,
 * and can be turned off process-wide with {@link setCaptureContent} or the
 * `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable. It is stripped
 * before any exporter that is not LiveKit Cloud's regardless — see `telemetry/pii.ts`.
 */
import type { Attributes, Span } from '@opentelemetry/api';
import type { ChatContext } from '../llm/chat_context.js';
import type { RealtimeModelMetrics } from '../metrics/base.js';
/**
 * Turn recording of GenAI message content on or off for the process.
 *
 * When off, spans still carry every non-content GenAI attribute (model, provider, token
 * usage, finish reasons, tool names), but `gen_ai.input.messages`, `gen_ai.output.messages`,
 * `gen_ai.system_instructions`, `gen_ai.tool.definitions` and
 * `gen_ai.tool.call.{arguments,result}` are omitted.
 */
export declare function setCaptureContent(enabled: boolean): void;
export interface MessagePart {
    type: string;
    [key: string]: unknown;
}
export interface ChatMessagePayload {
    role: string;
    parts: MessagePart[];
    finishReason?: string;
    [key: string]: unknown;
}
export interface InferenceMarker {
    recorded: boolean;
}
/** Runs `fn` with a marker that fills in if an `llm_request` span is created inside it. */
export declare function withInferenceTracking<T>(fn: (marker: InferenceMarker) => T): T;
/** Called where an `llm_request` span is created, so the enclosing node stands down. */
export declare function markInferenceSpanRecorded(): void;
/**
 * `gen_ai.system_instructions` — the agent instructions, as text parts.
 *
 * LiveKit carries an agent's instructions as `system`/`developer` messages in the chat
 * context, but they originate from the agent definition rather than from the conversation,
 * so they are reported as instructions rather than history.
 */
export declare function toSystemInstructions(chatCtx: ChatContext): MessagePart[];
/**
 * `gen_ai.input.messages` — the conversation history, in the order it was sent.
 *
 * `system`/`developer` messages are reported in `gen_ai.system_instructions` instead, and
 * non-conversational items (agent handoffs, config updates) are skipped.
 */
export declare function toInputMessages(chatCtx: ChatContext): ChatMessagePayload[];
export interface ToolCallLike {
    callId: string;
    name: string;
    args: string;
}
/** `gen_ai.output.messages` — the single assistant turn the model generated. */
export declare function toOutputMessages(params: {
    text?: string;
    functionCalls?: readonly ToolCallLike[];
    finishReason?: string;
}): ChatMessagePayload[];
/**
 * `parameters` is deliberately omitted: the convention marks it NOT RECOMMENDED by default
 * because a schema is large, and building one per request would be pure overhead for
 * telemetry. Tools are matched structurally for the layering reason above.
 */
export declare function toToolDefinitions(tools: readonly unknown[] | Record<string, unknown>): MessagePart[];
export declare function finishReasonFor(params: {
    functionCalls?: readonly unknown[];
    interrupted?: boolean;
}): string;
/**
 * `gen_ai.conversation.id` — the room a session runs in.
 *
 * The convention forbids fabricating one (no UUIDs, trace ids or content hashes), so this is
 * the room id LiveKit already stamps, and `undefined` outside a job context.
 */
export declare function conversationId(): string | undefined;
/** The `create_agent` / `invoke_agent` span attributes. */
/**
 * Record the convention's content attributes, when content capture is enabled.
 *
 * Values are JSON strings: OpenTelemetry attributes cannot hold structured values, which the
 * convention explicitly allows for spans.
 */
export declare function setContentAttributes(span: Span, content: {
    systemInstructions?: MessagePart[];
    inputMessages?: ChatMessagePayload[];
    outputMessages?: ChatMessagePayload[];
    toolDefinitions?: MessagePart[];
}): void;
/** The attributes the convention asks for at span creation time. */
export declare function setRequestAttributes(span: Span, params: {
    operation: string;
    provider?: string;
    model?: string;
    stream?: boolean;
    outputType?: string;
}): void;
export declare function setResponseAttributes(span: Span, params: {
    responseId?: string;
    model?: string;
    finishReasons?: string[];
    /** Time to first chunk, in seconds. */
    timeToFirstChunk?: number;
}): void;
/**
 * Token usage in the convention's names.
 *
 * Per the convention the detailed counts are subsets of the totals, so cached and reasoning
 * tokens are reported alongside — not added to — input and output tokens.
 */
export declare function setUsageAttributes(span: Span, usage: {
    promptTokens?: number;
    completionTokens?: number;
    promptCachedTokens?: number;
    cacheCreationTokens?: number;
    reasoningTokens?: number;
}): void;
/** Token usage for a realtime (speech-to-speech) turn, per modality. */
export declare function realtimeUsageAttributes(metrics: RealtimeModelMetrics): Attributes;
/** The `execute_tool` span's attributes, per the convention. */
export declare function setToolAttributes(span: Span, params: {
    name: string;
    callId?: string;
    toolType?: string;
    description?: string;
    /** Raw (typically JSON) arguments as produced by the model. */
    args?: string;
    agentName?: string;
}): void;
export declare function setToolResult(span: Span, params: {
    result?: string;
    isError: boolean;
}): void;
/**
 * `error.type` — a low-cardinality identifier, per the convention.
 *
 * Never the error message: that is free-form and may carry user data.
 */
export declare function setErrorType(span: Span, error: Error | string): void;
export declare function setAgentAttributes(span: Span, params: {
    operation: string;
    agentName: string;
    model?: string;
    provider?: string;
}): void;
/** The `invoke_workflow` span attributes — LiveKit's session is the workflow. */
export declare function setWorkflowAttributes(span: Span, params: {
    name: string;
}): void;
//# sourceMappingURL=gen_ai.d.ts.map