/**
 * One-liner bootstrap for the Introspection OTel surface.
 *
 * `init()` detects the installed LLM frameworks and wires them into one shared
 * pipeline:
 *
 * ```ts
 * import * as introspection from "@introspection-sdk/introspection-node/otel";
 *
 * await introspection.init({ serviceName: "my-app" });
 * // An installed Pi agent is wired into the shared provider automatically.
 * ```
 *
 * It also exposes the `track` / `feedback` / `identify` analytics surface and a
 * `conversation()` scope, proxied to a global {@link IntrospectionLogs}.
 */
import { type TracerProvider } from "@opentelemetry/api";
import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
import type { AdvancedOptions, FeedbackOptions, UserTraits } from "../types.js";
import { type Integration } from "./integrations/index.js";
import type { Agent } from "@earendil-works/pi-agent-core";
import type { AgentMeta } from "./pi.js";
import { IntrospectionLogs } from "./logs.js";
import { type ConflictBehavior } from "./setup.js";
/** Options for {@link init}. */
export interface InitOptions {
    /** Auth token. Falls back to `INTROSPECTION_TOKEN`. */
    token?: string;
    /** Service name for spans. Falls back to `INTROSPECTION_SERVICE_NAME`. */
    serviceName?: string;
    /** OTLP base URL. Falls back to `INTROSPECTION_BASE_OTEL_URL`. */
    baseUrl?: string;
    /**
     * Use this provider instead of creating one. The caller owns its span
     * processors (attach an {@link IntrospectionSpanProcessor} yourself).
     */
    tracerProvider?: TracerProvider;
    /**
     * Extra span processors composed onto the provider `init()` creates — the
     * one-call dual-export path. Each runs alongside the Introspection processor,
     * e.g. `init({ spanProcessors: [new BatchSpanProcessor(otherBackendExporter)] })`.
     * Ignored when `tracerProvider` is supplied.
     */
    spanProcessors?: SpanProcessor[];
    /** Extra integrations to install beyond auto-discovery. */
    integrations?: Integration[];
    /** Install every importable built-in integration (default `true`). */
    autoDiscover?: boolean;
    /** Behaviour when an OTel context manager / propagator is already registered. */
    onConflict?: ConflictBehavior;
    /** Advanced configuration (custom exporter, headers, …). */
    advanced?: AdvancedOptions;
}
/** Generate a fresh conversation id in the format the backend expects. */
export declare function newConversationId(): string;
/**
 * Detect installed LLM frameworks and wire them into one shared provider.
 *
 * Idempotent: repeated calls return the already-configured provider without
 * re-installing integrations.
 */
export declare function init(options?: InitOptions): Promise<TracerProvider>;
/** Return the global logs client. Throws if {@link init} has not been called. */
export declare function getClient(): IntrospectionLogs;
/** Return the shared provider. Throws if {@link init} has not been called. */
export declare function getTracerProvider(): TracerProvider;
/** Track an analytics event. Requires {@link init} first. */
export declare function track(eventName: string, properties?: Record<string, unknown>, options?: {
    eventId?: string;
}): void;
/** Record feedback on an AI response. Requires {@link init} first. */
export declare function feedback(name: string, options?: FeedbackOptions): void;
/** Associate the current context with a user. Requires {@link init} first. */
export declare function identify(userId: string, traits?: UserTraits, anonymousId?: string, eventId?: string): void;
/**
 * Run `callback` inside a conversation scope: every span/event produced within
 * is stamped with `gen_ai.conversation.id`. Generates an id when none is given.
 *
 * ```ts
 * await introspection.conversation((id) => client.messages.create({ ... }));
 * await introspection.conversation("conv_123", (id) => run());
 * ```
 *
 * Unlike the `with*` helpers below, this does not require {@link init}: a
 * conversation id is minted locally and scoped on W3C baggage, which is
 * ordinary OpenTelemetry context and needs no exporter behind it. Routing it
 * through the global client made `conversation()` throw before `init()` even
 * though nothing in it had anything to send -- so the id a caller wanted to
 * mint before configuring telemetry, or to hand to a service that exports on
 * its own, was unreachable.
 */
export declare function conversation<T>(callback: (conversationId: string) => T | Promise<T>): Promise<T>;
export declare function conversation<T>(conversationId: string, callback: (conversationId: string) => T | Promise<T>): Promise<T>;
/**
 * Run `callback` with `gen_ai.agent.name` (+ optional `gen_ai.agent.id`) on the
 * baggage, so spans/events produced within are attributed to that agent.
 * Requires {@link init} first. Mirrors `IntrospectionLogs.withAgent`.
 */
export declare function withAgent<T>(agentName: string, agentId: string | undefined, callback: () => T | Promise<T>): Promise<T>;
/**
 * Run `callback` inside a conversation scope, optionally chaining a previous
 * response id. Unlike {@link conversation}, the id is required (no auto-gen).
 * Requires {@link init} first.
 */
export declare function withConversation<T>(conversationId: string | undefined, previousResponseId: string | undefined, callback: () => T | Promise<T>): Promise<T>;
/** Run `callback` with `identity.user_id` on the baggage. Requires {@link init} first. */
export declare function withUserId<T>(userId: string, callback: () => T | Promise<T>): Promise<T>;
/** Run `callback` with `identity.anonymous_id` on the baggage. Requires {@link init} first. */
export declare function withAnonymousId<T>(anonymousId: string, callback: () => T | Promise<T>): Promise<T>;
/** Instrument a Pi `Agent` against the shared provider. Requires {@link init}. */
export declare function instrumentPi(agent: Agent, meta: AgentMeta): void;
/**
 * Flush and shut down the logs client and, if `init()` created it, the
 * provider.
 *
 * A provider you passed via `init({ tracerProvider })` is **yours** — this
 * leaves it running, so any processors you attached to it (a second
 * OTLP backend, for instance) are not flushed. Call `provider.shutdown()`
 * yourself after this.
 */
export declare function shutdown(): Promise<void>;
/** Reset module state. Test-only utility. */
export declare function _resetForTests(): void;
//# sourceMappingURL=init.d.ts.map