import { ILogWriter } from "../types";
import { Entity } from "./types";
/**
 * Configuration object for base container initialization.
 */
export type BaseConfig = {
    id: string;
    spanId?: string;
    name?: string;
    tags?: Record<string, string>;
    /**
     * Optional explicit start timestamp. If not provided, defaults to current time.
     */
    startTimestamp?: Date;
    /**
     * Optional explicit end timestamp. Can be set during creation for completed operations.
     */
    endTimestamp?: Date;
};
/**
 * Abstract base class for all logging containers in the Maxim SDK.
 *
 * Provides common functionality for managing container lifecycle, metadata, tags,
 * and communication with the log writer. All specific container types extend this class.
 *
 * @abstract
 * @class BaseContainer
 * @example
 * // BaseContainer is not instantiated directly, but through subclasses
 * const session = new Session({ id: 'session-1', name: 'User Chat' }, writer);
 * session.addTag('user_id', '12345');
 * session.addMetadata({ context: 'support_chat' });
 */
export declare abstract class BaseContainer {
    protected readonly entity: Entity;
    protected _id: string;
    protected _name?: string;
    protected spanId?: string;
    protected readonly startTimestamp: Date;
    protected endTimestamp?: Date;
    protected tags: Record<string, string>;
    protected readonly writer: ILogWriter;
    /**
     * Creates a new base container instance.
     *
     * @param entity - The entity type this container represents
     * @param config - Configuration for the container
     * @param writer - Log writer instance for committing changes
     * @throws {Error} When the provided ID contains invalid characters (only alphanumeric, hyphens, and underscores allowed; only throws if you have `raiseExceptions` config set to true)
     */
    constructor(entity: Entity, config: BaseConfig, writer: ILogWriter);
    /**
     * Gets the unique identifier for this container.
     *
     * @returns The container's unique ID
     */
    get id(): string;
    /**
     * Adds a tag to this container for categorization and filtering.
     *
     * @param key - The tag key
     * @param value - The tag value
     * @returns void
     * @example
     * container.addTag('environment', 'production');
     * container.addTag('user_type', 'premium');
     */
    addTag(key: string, value: string): void;
    /**
     * Static method to add a tag to any container by ID.
     *
     * @param writer - The log writer instance
     * @param entity - The entity type
     * @param id - The container ID
     * @param key - The tag key
     * @param value - The tag value
     * @returns void
     */
    static addTag_(writer: ILogWriter, entity: Entity, id: string, key: string, value: string): void;
    /**
     * Adds metadata to this container for additional context and debugging. Any data type could be added as the value in the metadata record.
     *
     * @param metadata - Key-value pairs of metadata
     * @returns void
     * @example
     * container.addMetadata({
     *   requestId: 'req-123',
     *   userAgent: 'Mozilla/5.0...',
     *   processingTime: 1500
     * });
     */
    addMetadata(metadata: Record<string, unknown>): void;
    /**
     * Static method to add metadata to any container by ID.
     *
     * @param writer - The log writer instance
     * @param entity - The entity type
     * @param id - The container ID
     * @param metadata - The metadata to add
     * @returns void
     */
    static addMetadata_(writer: ILogWriter, entity: Entity, id: string, metadata: Record<string, unknown>): void;
    /**
     * Marks this container as ended and records the end timestamp.
     *
     * @param endTimestamp - Optional explicit end timestamp. If not provided, defaults to current time.
     * @returns void
     * @example
     * // End a container when processing is complete
     * container.end();
     *
     * @example
     * // End with explicit timestamp
     * container.end(new Date('2024-01-15T10:30:00Z'));
     */
    end(endTimestamp?: Date): void;
    /**
     * Static method to end any container by ID.
     *
     * @param writer - The log writer instance
     * @param entity - The entity type
     * @param id - The container ID
     * @param data - Optional additional data to include with the end event
     * @returns void
     */
    static end_(writer: ILogWriter, entity: Entity, id: string, data?: any): void;
    /**
     * Returns the current data state of this container.
     *
     * @returns The container's data.
     */
    data(): any;
    /**
     * Commits a change to this container via the log writer.
     *
     * @protected
     * @param action - The action being performed
     * @param data - Data associated with the action
     * @returns void
     */
    protected commit(action: string, data?: any): void;
    /**
     * Static method to commit changes to any container by ID.
     *
     * @protected
     * @param writer - The log writer instance
     * @param entity - The entity type
     * @param id - The container ID
     * @param action - The action being performed
     * @param data - Data associated with the action
     * @returns void
     */
    protected static commit_(writer: ILogWriter, entity: Entity, id: string, action: string, data?: any): void;
}
/**
 * Extended base container that supports evaluation functionality.
 *
 * Provides additional capabilities for containers that can be evaluated,
 * such as sessions, traces, generations, and retrievals. Includes methods
 * for triggering evaluations.
 *
 * @abstract
 * @class EvaluatableBaseContainer
 * @extends BaseContainer
 */
export declare abstract class EvaluatableBaseContainer extends BaseContainer {
    /**
     * Gets the evaluation methods for this container.
     *
     * @returns Evaluation methods for configuring and triggering evaluations
     * @example
     * container.evaluate.withEvaluators('bias', 'toxicity');
     */
    get evaluate(): EvaluateContainer;
    /**
     * Static method to get evaluation methods for any evaluatable container by ID.
     *
     * @param writer - The log writer instance
     * @param entity - The entity type
     * @param id - The container ID
     * @returns Evaluation methods for configuring and triggering evaluations
     */
    static evaluate_(writer: ILogWriter, entity: Entity, id: string): EvaluateContainer;
}
/**
 * Extended evaluatable container that supports event emission.
 *
 * Provides capabilities for containers that can emit events. Used by traces and spans.
 *
 * @abstract
 * @class EventEmittingBaseContainer
 * @extends EvaluatableBaseContainer
 */
export declare abstract class EventEmittingBaseContainer extends EvaluatableBaseContainer {
    /**
     * Emits a custom event within this container.
     *
     * @param id - Unique identifier for the event
     * @param name - Human-readable name for the event
     * @param tags - Optional tags for categorizing the event
     * @param metadata - Optional metadata for additional context
     * @returns void
     * @example
     * container.event(
     *   'checkpoint-1',
     *   'Processing Milestone',
     *   { phase: 'preprocessing', status: 'complete' },
     *   { itemsProcessed: 1000, timeElapsed: 5.2 }
     * );
     */
    event(id: string, name: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
    /**
     * Static method to emit an event for any event-emitting container by ID.
     *
     * @param writer - The log writer instance
     * @param entity - The entity type
     * @param id - The container ID
     * @param eventId - Unique identifier for the event
     * @param name - Human-readable name for the event
     * @param tags - Optional tags for categorizing the event
     * @param metadata - Optional metadata for additional context
     * @returns void
     */
    static event_(writer: ILogWriter, entity: Entity, id: string, eventId: string, name: string, tags?: Record<string, string>, metadata?: Record<string, unknown>): void;
}
/**
 * Container for configuring and triggering evaluations on containers.
 *
 * Provides an interface for setting up evaluations with variables.
 * Used to assess the quality and performance of different operations
 * for your application.
 *
 * @class EvaluateContainer
 * @example
 // Attaching evaluators to a container
 * container.evaluate
 *   .withEvaluators('bias', 'toxicity')
 *    // Optionally, directly chain variables for the evaluators mentioned above
 *   .withVariables({ context: 'user_query', expected: 'gold_standard' });
 *
 * @example
 * // Attaching variables at a later stage to specific evaluators
 * container.evaluate
 *   .withVariables({ context: 'user_query', expected: 'gold_standard' }, ['bias']);
 */
export declare class EvaluateContainer {
    private _writer;
    private _entity;
    private _id;
    /**
     * Creates a new evaluation container instance.
     *
     * @param writer - The log writer instance for committing evaluations
     * @param entity - The entity type being evaluated
     * @param id - The unique identifier of the entity being evaluated
     * @example
     * // Usually created through container.evaluate getter
     * const evaluator = new EvaluateContainer(writer, Entity.GENERATION, 'gen-123');
     */
    constructor(writer: ILogWriter, entity: Entity, id: string);
    /**
     * Configures variables for specific evaluators in the evaluation.
     *
     * Variables provide the values needed by the evaluators to
     * execute; such as expected outputs, retrieved contexts, or input queries.
     *
     * @template T - String literal type for variable names
     * @param variables - Key-value pairs mapping variables to their values
     * @param forEvaluators - Array of evaluator names that should receive these variables
     * @example
     * // Provide expected output for `accuracy` evaluator
     * container.evaluate
     *   .withVariables(
     *     { expected_output: 'The correct answer is 42' },
     *     ['bias']
     *   )
     *
     * @example
     * // Multiple variables for different evaluators
     * container.evaluate
     *   .withVariables(
     *     { context: 'Retrieved documents...', user_query: 'What is AI?' },
     *     ['bias', 'toxicity']
     *   );
     */
    withVariables<T extends string = string>(variables: Record<T, string>, forEvaluators: string[]): void;
    /**
     * Specifies which evaluators should be attached for evaluation to this container.
     *
     * @template T - String literal type for evaluator names
     * @param evaluators - Names of evaluators to be used for evaluation once all variables are available to them
     * @example
     * // Use built-in evaluators
     * container.evaluate
     *   .withEvaluators('bias', 'toxicity');
     *
     * @example
     * // Mix of built-in and custom evaluators
     * container.evaluate
     *   .withEvaluators(
     *     'bias',
     *     'custom_domain_knowledge',
     *     'brand_compliance'
     *   );
     */
    withEvaluators<T extends string = string>(...evaluators: string[]): {
        withVariables: <U extends string = T>(variables: Record<U, string>) => void;
    };
}