@doclo/core 0.1.5

package/dist/observability/index.d.ts

@@ -0,0 +1,933 @@
+/**
+ * SDK Observability Hooks
+ *
+ * Comprehensive observability system for the doclo-sdk SDK.
+ * All hooks are optional and async-capable. Hooks never crash execution.
+ *
+ * @module @doclo/core/observability
+ */
+/**
+ * Hook Execution Order Guarantees:
+ *
+ * 1. onFlowStart - Called BEFORE any steps execute
+ * 2. onStepStart - Called BEFORE step execution
+ * 3. onStepEnd/onStepError - Called AFTER step completes (mutually exclusive)
+ * 4. onConsensusStart - Called BEFORE first consensus run
+ * 5. onConsensusRunRetry - Called when a consensus run will be retried (before retry)
+ * 6. onConsensusRunComplete - Called after EACH consensus run completes (after all retries)
+ * 7. onConsensusComplete - Called AFTER all consensus runs and agreement reached
+ * 8. onFlowEnd/onFlowError - Called AFTER all steps complete (mutually exclusive)
+ *
+ * Async Behavior:
+ * - SDK WILL wait for async hooks to complete before continuing
+ * - Exception: Logs (onLog) are fire-and-forget, no waiting
+ * - Hooks run serially, not in parallel
+ * - If hook exceeds timeout, SDK logs warning and continues
+ *
+ * State Isolation:
+ * - Hooks cannot modify execution state (read-only by default)
+ * - Each hook receives immutable context snapshot
+ * - Hooks cannot access other hooks' execution
+ */
+interface ObservabilityConfig {
+    /** Called when flow execution begins */
+    onFlowStart?: (context: FlowStartContext) => void | Promise<void>;
+    /** Called when flow completes successfully */
+    onFlowEnd?: (context: FlowEndContext) => void | Promise<void>;
+    /** Called when flow fails or is cancelled */
+    onFlowError?: (context: FlowErrorContext) => void | Promise<void>;
+    /** Called before each step executes */
+    onStepStart?: (context: StepStartContext) => void | Promise<void>;
+    /** Called after step completes successfully */
+    onStepEnd?: (context: StepEndContext) => void | Promise<void>;
+    /** Called when step fails */
+    onStepError?: (context: StepErrorContext) => void | Promise<void>;
+    /** Called when consensus decision begins */
+    onConsensusStart?: (context: ConsensusStartContext) => void | Promise<void>;
+    /** Called when a consensus run will be retried (empty result or error) */
+    onConsensusRunRetry?: (context: ConsensusRunRetryContext) => void | Promise<void>;
+    /** Called after each individual consensus run (after all retries for that run) */
+    onConsensusRunComplete?: (context: ConsensusRunContext) => void | Promise<void>;
+    /** Called when consensus decision is reached */
+    onConsensusComplete?: (context: ConsensusCompleteContext) => void | Promise<void>;
+    /** Called when batch processing begins */
+    onBatchStart?: (context: BatchStartContext) => void | Promise<void>;
+    /** Called before each batch item is processed */
+    onBatchItemStart?: (context: BatchItemContext) => void | Promise<void>;
+    /** Called after each batch item completes */
+    onBatchItemEnd?: (context: BatchItemEndContext) => void | Promise<void>;
+    /** Called when batch processing completes */
+    onBatchEnd?: (context: BatchEndContext) => void | Promise<void>;
+    /** Called before making a provider request */
+    onProviderRequest?: (context: ProviderRequestContext) => void | Promise<void>;
+    /** Called after successful provider response */
+    onProviderResponse?: (context: ProviderResponseContext) => void | Promise<void>;
+    /** Called when provider call will be retried */
+    onProviderRetry?: (context: ProviderRetryContext) => void | Promise<void>;
+    /** Called when circuit breaker opens for a provider */
+    onCircuitBreakerTriggered?: (context: CircuitBreakerContext) => void | Promise<void>;
+    /** Called for internal SDK log events (fire-and-forget) */
+    onLog?: (context: LogContext) => void | Promise<void>;
+    /** Called when a hook itself throws an error */
+    onHookError?: (error: HookError) => void;
+    /** If true, hook errors will crash execution. Default: false (hooks never crash) */
+    failOnHookError?: boolean;
+    /** Max milliseconds to wait for async hooks. Default: 5000 */
+    hookTimeout?: number;
+    /** Enable/disable all hooks. Default: true */
+    enabled?: boolean;
+    /** Sampling rate 0.0 to 1.0. Default: 1.0 (100%) */
+    samplingRate?: number;
+    /** Sampling strategy. Default: 'random' */
+    samplingStrategy?: 'random' | 'custom';
+    /** Custom sampler function (only used if samplingStrategy is 'custom') */
+    customSampler?: (context: FlowStartContext) => boolean;
+    /** Wait for async hooks to complete. Default: true */
+    asyncHooks?: boolean;
+    /** Don't wait for hooks (fire-and-forget). Default: false */
+    fireAndForget?: boolean;
+    /** Custom trace ID generator. Default: crypto-secure random */
+    generateTraceId?: () => string;
+    /** Custom span ID generator. Default: crypto-secure random */
+    generateSpanId?: () => string;
+    /** Custom execution ID generator. Default: crypto-secure random */
+    generateExecutionId?: () => string;
+    /** Propagate existing trace context (for distributed tracing) */
+    traceContext?: TraceContextInput;
+    /** Observability contract version. Default: "1.0.0" */
+    observabilityVersion?: string;
+}
+interface FlowStartContext {
+    flowId: string;
+    flowVersion: string;
+    executionId: string;
+    timestamp: number;
+    input: unknown;
+    config: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    sdkVersion: string;
+    observabilityVersion: string;
+    traceContext: TraceContext;
+}
+interface FlowEndContext {
+    flowId: string;
+    executionId: string;
+    timestamp: number;
+    startTime: number;
+    duration: number;
+    output: unknown;
+    stats: FlowStats;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface FlowErrorContext {
+    flowId: string;
+    executionId: string;
+    timestamp: number;
+    startTime: number;
+    duration: number;
+    error: Error;
+    errorCode?: string;
+    failedAtStepIndex?: number;
+    partialStats: FlowStats;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface FlowStats {
+    stepsTotal: number;
+    stepsCompleted: number;
+    stepsFailed: number;
+    totalTokens: number;
+    totalCost: number;
+    pagesProcessed?: number;
+    documentsProcessed?: number;
+}
+interface StepStartContext {
+    flowId: string;
+    executionId: string;
+    stepId: string;
+    stepIndex: number;
+    stepType: string;
+    stepName: string;
+    timestamp: number;
+    provider?: string;
+    model?: string;
+    config: {
+        maxTokens?: number;
+        temperature?: number;
+        topP?: number;
+        topK?: number;
+    };
+    input: unknown;
+    isConsensusEnabled: boolean;
+    consensusConfig?: {
+        runs: number;
+        strategy: 'majority' | 'unanimous';
+    };
+    isRetry: boolean;
+    retryAttempt?: number;
+    maxRetries?: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+    spanId: string;
+}
+interface StepEndContext {
+    flowId: string;
+    executionId: string;
+    stepId: string;
+    stepIndex: number;
+    timestamp: number;
+    startTime: number;
+    /**
+     * Duration of THIS step's own work only (not rolled-up from children).
+     * - For 'leaf' steps: The actual API call duration
+     * - For 'wrapper' steps: The step's own API call if any, or ~0ms for pure wrappers
+     * - For 'prep' steps: The preparation time (usually minimal)
+     */
+    duration: number;
+    output: unknown;
+    /**
+     * Token usage for THIS step's own API call only (not rolled-up from children).
+     * - For 'leaf' steps: The actual token usage
+     * - For 'wrapper' steps: Tokens from step's own call (e.g., categorize), or 0 for pure wrappers
+     * - For 'prep' steps: Always 0
+     */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    };
+    /**
+     * Cost of THIS step's own API call only (not rolled-up from children).
+     * - For 'leaf' steps: The actual cost
+     * - For 'wrapper' steps: Cost from step's own call (e.g., categorize), or $0 for pure wrappers
+     * - For 'prep' steps: Always $0
+     */
+    cost: number;
+    /**
+     * Type of step for metrics interpretation:
+     * - 'leaf': Actual LLM/API call (parse, extract, categorize single call)
+     * - 'wrapper': Orchestration step with children (conditional, consensus parent, forEach)
+     * - 'prep': Utility step with no API call (output node, data transformation)
+     */
+    metricKind: 'leaf' | 'wrapper' | 'prep';
+    responseId?: string;
+    finishReason?: string;
+    modelUsed?: string;
+    httpStatusCode?: number;
+    httpMethod?: string;
+    httpUrl?: string;
+    otelAttributes: Record<string, string | number | boolean>;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+    spanId: string;
+}
+interface StepErrorContext {
+    flowId: string;
+    executionId: string;
+    stepId: string;
+    stepIndex: number;
+    timestamp: number;
+    startTime: number;
+    duration: number;
+    error: Error;
+    errorCode?: string;
+    partialUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    };
+    partialCost?: number;
+    willRetry: boolean;
+    retryAttempt?: number;
+    nextRetryDelay?: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+    spanId: string;
+}
+interface ConsensusStartContext {
+    flowId: string;
+    executionId: string;
+    stepId: string;
+    timestamp: number;
+    runsPlanned: number;
+    strategy: 'majority' | 'unanimous';
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface ConsensusRunContext {
+    flowId: string;
+    executionId: string;
+    parentStepId: string;
+    consensusRunId: string;
+    runIndex: number;
+    timestamp: number;
+    startTime: number;
+    duration: number;
+    output: unknown;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    };
+    cost: number;
+    status: 'success' | 'failed';
+    error?: Error;
+    totalAttempts: number;
+    wasRetried: boolean;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface ConsensusCompleteContext {
+    flowId: string;
+    executionId: string;
+    stepId: string;
+    timestamp: number;
+    totalRuns: number;
+    successfulRuns: number;
+    failedRuns: number;
+    agreement: number;
+    agreedOutput: unknown;
+    totalUsage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    };
+    totalCost: number;
+    totalRetries: number;
+    runsWithRetries: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+/**
+ * Context for consensus run retry events.
+ * Fires immediately when a retry is about to occur (before the retry attempt).
+ */
+interface ConsensusRunRetryContext {
+    flowId: string;
+    executionId: string;
+    parentStepId: string;
+    consensusRunId: string;
+    runIndex: number;
+    timestamp: number;
+    attemptNumber: number;
+    maxAttempts: number;
+    reason: 'empty_result' | 'error';
+    error?: Error;
+    partialUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    partialCost?: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface BatchStartContext {
+    flowId: string;
+    executionId: string;
+    batchId: string;
+    stepId: string;
+    totalItems: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface BatchItemContext {
+    flowId: string;
+    executionId: string;
+    batchId: string;
+    stepId: string;
+    itemIndex: number;
+    totalItems: number;
+    item: unknown;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface BatchItemEndContext extends BatchItemContext {
+    result: unknown;
+    duration: number;
+    error?: Error;
+    status: 'success' | 'failed';
+}
+interface BatchEndContext {
+    flowId: string;
+    executionId: string;
+    batchId: string;
+    stepId: string;
+    timestamp: number;
+    startTime: number;
+    duration: number;
+    totalItems: number;
+    successfulItems: number;
+    failedItems: number;
+    results: unknown[];
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface ProviderRequestContext {
+    flowId: string;
+    executionId: string;
+    stepId?: string;
+    timestamp: number;
+    provider: string;
+    model: string;
+    input: unknown;
+    schema?: unknown;
+    httpMethod?: string;
+    httpUrl?: string;
+    attemptNumber: number;
+    maxAttempts?: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface ProviderResponseContext {
+    flowId: string;
+    executionId: string;
+    stepId?: string;
+    timestamp: number;
+    startTime: number;
+    duration: number;
+    provider: string;
+    model: string;
+    modelUsed?: string;
+    output: unknown;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+    };
+    cost?: number;
+    httpStatusCode?: number;
+    httpMethod?: string;
+    httpUrl?: string;
+    responseId?: string;
+    finishReason?: string;
+    attemptNumber: number;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface ProviderRetryContext {
+    flowId: string;
+    executionId: string;
+    stepId?: string;
+    timestamp: number;
+    provider: string;
+    model: string;
+    error: Error;
+    errorCode?: string;
+    attemptNumber: number;
+    maxAttempts: number;
+    nextRetryDelay: number;
+    partialUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface CircuitBreakerContext {
+    flowId: string;
+    executionId: string;
+    timestamp: number;
+    provider: string;
+    model?: string;
+    failureCount: number;
+    threshold: number;
+    cooldownMs: number;
+    lastError?: Error;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+interface LogContext {
+    flowId: string;
+    executionId: string;
+    stepId?: string;
+    timestamp: number;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    metadata?: Record<string, unknown>;
+    traceContext: TraceContext;
+}
+/**
+ * Union of all possible hook context types.
+ * Used for generic hook handling where the specific type is unknown.
+ */
+type HookContext = FlowStartContext | FlowEndContext | FlowErrorContext | StepStartContext | StepEndContext | StepErrorContext | ConsensusStartContext | ConsensusRunContext | ConsensusCompleteContext | ConsensusRunRetryContext | BatchStartContext | BatchItemContext | BatchItemEndContext | BatchEndContext | ProviderRequestContext | ProviderResponseContext | ProviderRetryContext | CircuitBreakerContext | LogContext;
+interface HookError {
+    hookName: string;
+    error: Error;
+    context: HookContext;
+    timestamp: number;
+}
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceFlags: number;
+    traceState?: string;
+}
+interface TraceContextInput {
+    traceId: string;
+    parentSpanId: string;
+    traceFlags?: number;
+    traceState?: string;
+}
+interface ExecutionContext {
+    flowId: string;
+    executionId: string;
+    currentStepId?: string;
+    currentStepIndex?: number;
+    startTime: number;
+    status: 'running' | 'completed' | 'failed';
+    customAttributes: Record<string, unknown>;
+    customMetrics: CustomMetric[];
+}
+interface CustomMetric {
+    name: string;
+    value: number;
+    unit?: string;
+    timestamp: number;
+}
+
+/**
+ * Hook Executor
+ *
+ * Executes observability hooks with timeout protection and error isolation.
+ * Ensures hooks never crash flow execution.
+ *
+ * @module @doclo/core/observability/hook-executor
+ */
+
+/**
+ * Generic hook function type.
+ * The context parameter accepts any hook context type since this executor
+ * handles all observability hooks (onFlowStart, onStepEnd, onLog, etc.).
+ * Each specific hook in ObservabilityConfig has its own typed signature.
+ */
+type GenericHookFunction = (context: any) => void | Promise<void>;
+/**
+ * Hook execution options
+ */
+interface HookExecutionOptions {
+    /** Hook name for error reporting */
+    hookName: string;
+    /** Observability configuration */
+    config: ObservabilityConfig;
+    /** Context passed to hook - specific type depends on which hook is being called */
+    context: HookContext;
+    /** Whether this is a fire-and-forget hook (e.g., onLog) */
+    fireAndForget?: boolean;
+}
+/**
+ * Execute a hook with timeout protection and error isolation
+ *
+ * @param hook - The hook function to execute
+ * @param options - Execution options
+ * @returns Promise that resolves when hook completes (or times out)
+ */
+declare function executeHook(hook: GenericHookFunction | undefined, options: HookExecutionOptions): Promise<void>;
+/**
+ * Execute multiple hooks serially with timeout protection
+ *
+ * This ensures hooks run one at a time in the order they're provided.
+ *
+ * @param hooks - Array of hook execution configs
+ */
+declare function executeHooksSerial(hooks: Array<{
+    hook: GenericHookFunction | undefined;
+    options: HookExecutionOptions;
+}>): Promise<void>;
+/**
+ * Check if observability is enabled for this execution
+ *
+ * Takes sampling into account.
+ */
+declare function isObservabilityEnabled(config: ObservabilityConfig): boolean;
+
+/**
+ * Trace Context Generator
+ *
+ * Implements W3C Trace Context standard for distributed tracing.
+ * Generates crypto-secure trace IDs, span IDs, and execution IDs.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ * @module @doclo/core/observability/trace-context
+ */
+
+/**
+ * Trace flags for sampled traces
+ */
+declare const TRACE_FLAGS_SAMPLED = 1;
+/**
+ * Trace flags for non-sampled traces
+ */
+declare const TRACE_FLAGS_NOT_SAMPLED = 0;
+/**
+ * Generate a crypto-secure trace ID (32 lowercase hex characters)
+ *
+ * Format: 32 hex digits (16 bytes)
+ * Example: "4bf92f3577b34da6a3ce929d0e0e4736"
+ */
+declare function generateTraceId(): string;
+/**
+ * Generate a crypto-secure span ID (16 lowercase hex characters)
+ *
+ * Format: 16 hex digits (8 bytes)
+ * Example: "00f067aa0ba902b7"
+ */
+declare function generateSpanId(): string;
+/**
+ * Generate a unique execution ID
+ *
+ * Uses crypto-secure random bytes for uniqueness.
+ * Format: UUID v4 style (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
+ */
+declare function generateExecutionId(): string;
+/**
+ * Create a new trace context for flow execution
+ *
+ * @param config - Observability configuration
+ * @param sampled - Whether this execution is sampled
+ * @returns Complete trace context
+ */
+declare function createTraceContext(config: ObservabilityConfig, sampled: boolean): TraceContext;
+/**
+ * Create a child span context from a parent trace context
+ *
+ * @param parent - Parent trace context
+ * @param config - Observability configuration (for custom span ID generator)
+ * @returns New trace context with same traceId but new spanId
+ */
+declare function createChildSpanContext(parent: TraceContext, config?: ObservabilityConfig): TraceContext;
+/**
+ * Format trace context as W3C traceparent header value
+ *
+ * Format: "00-{traceId}-{spanId}-{flags}"
+ * Example: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+ *
+ * @see https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+declare function formatTraceparent(context: TraceContext): string;
+/**
+ * Parse W3C traceparent header value
+ *
+ * @param traceparent - Traceparent header value
+ * @returns Parsed trace context input or null if invalid
+ */
+declare function parseTraceparent(traceparent: string): TraceContextInput | null;
+/**
+ * Format trace context as W3C tracestate header value
+ *
+ * @see https://www.w3.org/TR/trace-context/#tracestate-header
+ */
+declare function formatTracestate(context: TraceContext): string | undefined;
+/**
+ * Check if trace context is sampled
+ */
+declare function isTraceSampled(context: TraceContext): boolean;
+/**
+ * Validate trace ID format
+ *
+ * Must be 32 lowercase hex characters, not all zeros
+ */
+declare function isValidTraceId(traceId: string): boolean;
+/**
+ * Validate span ID format
+ *
+ * Must be 16 lowercase hex characters, not all zeros
+ */
+declare function isValidSpanId(spanId: string): boolean;
+/**
+ * Trace Context Manager
+ *
+ * Manages trace context for the current execution.
+ */
+declare class TraceContextManager {
+    private traceContext;
+    private config;
+    constructor(config: ObservabilityConfig);
+    /**
+     * Initialize trace context for new execution
+     */
+    initialize(sampled: boolean): TraceContext;
+    /**
+     * Get current trace context
+     */
+    getTraceContext(): TraceContext | null;
+    /**
+     * Create child span context
+     */
+    createChildSpan(): TraceContext;
+    /**
+     * Get traceparent header value
+     */
+    getTraceparent(): string | null;
+    /**
+     * Reset trace context (for testing)
+     */
+    reset(): void;
+}
+
+/**
+ * OpenTelemetry Semantic Conventions for Gen AI
+ *
+ * Implements Gen AI semantic conventions (v1.29.0) for observability.
+ * Maps SDK data to standard OpenTelemetry attributes.
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ * @module @doclo/core/observability/otel-attributes
+ */
+/**
+ * Build OpenTelemetry attributes for LLM operations
+ *
+ * @param data - Step execution data
+ * @returns OpenTelemetry attributes object
+ */
+declare function buildOtelAttributes(data: {
+    provider?: string;
+    model?: string;
+    modelUsed?: string;
+    stepType?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    finishReason?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    topK?: number;
+}): Record<string, string | number | boolean>;
+/**
+ * Build OpenTelemetry attributes for provider requests
+ *
+ * Used for onProviderRequest hooks
+ */
+declare function buildProviderRequestAttributes(data: {
+    provider: string;
+    model: string;
+    config?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        topK?: number;
+    };
+}): Record<string, string | number | boolean>;
+/**
+ * Build OpenTelemetry attributes for provider responses
+ *
+ * Used for onProviderResponse hooks
+ */
+declare function buildProviderResponseAttributes(data: {
+    provider: string;
+    model: string;
+    modelUsed?: string;
+    inputTokens: number;
+    outputTokens: number;
+    finishReason?: string;
+}): Record<string, string | number | boolean>;
+/**
+ * Build OpenTelemetry attributes for step execution
+ *
+ * Used for onStepEnd hooks
+ */
+declare function buildStepAttributes(data: {
+    stepType: string;
+    provider?: string;
+    model?: string;
+    modelUsed?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    finishReason?: string;
+    config?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        topK?: number;
+    };
+}): Record<string, string | number | boolean>;
+/**
+ * Standard finish reason mappings
+ *
+ * Maps provider-specific finish reasons to standard values
+ */
+declare const FINISH_REASON_MAPPING: Record<string, string>;
+/**
+ * Normalize finish reason to standard value
+ */
+declare function normalizeFinishReason(reason: string | undefined): string | undefined;
+/**
+ * Add standard OpenTelemetry span attributes
+ *
+ * These are generic attributes that apply to all spans
+ */
+declare function addStandardSpanAttributes(attributes: Record<string, string | number | boolean>, data: {
+    spanKind?: 'client' | 'server' | 'internal';
+    serviceName?: string;
+    serviceVersion?: string;
+}): void;
+/**
+ * Build full OpenTelemetry context for export
+ *
+ * Combines Gen AI attributes with standard span attributes
+ */
+declare function buildFullOtelContext(data: {
+    stepType?: string;
+    provider?: string;
+    model?: string;
+    modelUsed?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    finishReason?: string;
+    config?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        topK?: number;
+    };
+    spanKind?: 'client' | 'server' | 'internal';
+    serviceName?: string;
+    serviceVersion?: string;
+}): Record<string, string | number | boolean>;
+
+/**
+ * Observability Configuration Defaults
+ *
+ * Provides default configuration values and config merging utilities.
+ *
+ * @module @doclo/core/observability/defaults
+ */
+
+/**
+ * Default observability configuration
+ */
+declare const DEFAULT_OBSERVABILITY_CONFIG: Required<Omit<ObservabilityConfig, 'onFlowStart' | 'onFlowEnd' | 'onFlowError' | 'onStepStart' | 'onStepEnd' | 'onStepError' | 'onConsensusStart' | 'onConsensusRunRetry' | 'onConsensusRunComplete' | 'onConsensusComplete' | 'onBatchStart' | 'onBatchItemStart' | 'onBatchItemEnd' | 'onBatchEnd' | 'onProviderRequest' | 'onProviderResponse' | 'onProviderRetry' | 'onCircuitBreakerTriggered' | 'onLog' | 'onHookError' | 'customSampler' | 'generateTraceId' | 'generateSpanId' | 'generateExecutionId' | 'traceContext' | 'observabilityVersion'>>;
+/**
+ * Merge user config with defaults
+ *
+ * User config takes precedence over defaults.
+ */
+declare function mergeConfig(userConfig?: ObservabilityConfig): ObservabilityConfig;
+/**
+ * Determine if execution should be sampled
+ *
+ * Uses sampling strategy from config.
+ */
+declare function shouldSample(config: ObservabilityConfig): boolean;
+/**
+ * Validate observability configuration
+ *
+ * Checks for invalid values and warns about issues.
+ */
+declare function validateConfig(config: ObservabilityConfig): {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+};
+/**
+ * Get observability version
+ *
+ * Returns the version of the observability contract.
+ */
+declare function getObservabilityVersion(config?: ObservabilityConfig): string;
+/**
+ * Check if observability is effectively disabled
+ *
+ * Returns true if observability is explicitly disabled or sampling rate is 0.
+ */
+declare function isObservabilityDisabled(config: ObservabilityConfig): boolean;
+/**
+ * Check if any hooks are configured
+ *
+ * Returns true if at least one hook is defined.
+ */
+declare function hasAnyHooks(config: ObservabilityConfig): boolean;
+/**
+ * Create minimal config for testing
+ *
+ * Useful for unit tests that don't need full observability.
+ */
+declare function createMinimalConfig(overrides?: Partial<ObservabilityConfig>): ObservabilityConfig;
+
+/**
+ * Logging Utility for Observability
+ *
+ * Provides a logger that integrates with the observability system.
+ * Logs are sent to the onLog hook with fire-and-forget execution.
+ *
+ * @module @doclo/core/observability/logger
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LoggerOptions {
+    observability?: ObservabilityConfig;
+    flowId?: string;
+    executionId?: string;
+    stepId?: string;
+    traceContext?: TraceContext;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Logger class that integrates with observability hooks
+ */
+declare class Logger {
+    private options;
+    constructor(options?: LoggerOptions);
+    /**
+     * Log a debug message
+     */
+    debug(message: string, data?: unknown): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, data?: unknown): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, data?: unknown): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: Error | unknown, data?: unknown): void;
+    /**
+     * Internal log method that sends to onLog hook
+     */
+    private log;
+}
+/**
+ * Create a logger instance with observability integration
+ */
+declare function createLogger(options?: LoggerOptions): Logger;
+
+/**
+ * Observability Module
+ *
+ * Comprehensive observability system for the doclo-sdk SDK.
+ * Provides hooks, tracing, and monitoring capabilities.
+ *
+ * @module @doclo/core/observability
+ * @example
+ * ```typescript
+ * import { ObservabilityConfig } from '@doclo/core/observability';
+ *
+ * const config: ObservabilityConfig = {
+ *   onFlowStart: (ctx) => console.log('Flow started:', ctx.flowId),
+ *   onStepEnd: (ctx) => console.log('Step completed:', ctx.stepId, ctx.duration),
+ * };
+ * ```
+ */
+
+/**
+ * Observability module version
+ */
+declare const OBSERVABILITY_VERSION = "1.0.0";
+
+export { type BatchEndContext, type BatchItemContext, type BatchItemEndContext, type BatchStartContext, type CircuitBreakerContext, type ConsensusCompleteContext, type ConsensusRunContext, type ConsensusRunRetryContext, type ConsensusStartContext, type CustomMetric, DEFAULT_OBSERVABILITY_CONFIG, type ExecutionContext, FINISH_REASON_MAPPING, type FlowEndContext, type FlowErrorContext, type FlowStartContext, type FlowStats, type HookError, type LogContext, type LogLevel, Logger, type LoggerOptions, OBSERVABILITY_VERSION, type ObservabilityConfig, type ProviderRequestContext, type ProviderResponseContext, type ProviderRetryContext, type StepEndContext, type StepErrorContext, type StepStartContext, TRACE_FLAGS_NOT_SAMPLED, TRACE_FLAGS_SAMPLED, type TraceContext, type TraceContextInput, TraceContextManager, addStandardSpanAttributes, buildFullOtelContext, buildOtelAttributes, buildProviderRequestAttributes, buildProviderResponseAttributes, buildStepAttributes, createChildSpanContext, createLogger, createMinimalConfig, createTraceContext, executeHook, executeHooksSerial, formatTraceparent, formatTracestate, generateExecutionId, generateSpanId, generateTraceId, getObservabilityVersion, hasAnyHooks, isObservabilityDisabled, isObservabilityEnabled, isTraceSampled, isValidSpanId, isValidTraceId, mergeConfig, normalizeFinishReason, parseTraceparent, shouldSample, validateConfig };