/**
 * Main RLM (Recursive Language Model) class.
 *
 * Provides the primary API for recursive completions, structured output,
 * streaming, file-based context, caching, retry/resilience, and events.
 *
 * @example
 * ```typescript
 * import { RLM } from 'recursive-llm-ts';
 *
 * const rlm = new RLM('gpt-4o-mini', { api_key: process.env.OPENAI_API_KEY });
 * const result = await rlm.completion('Summarize this', longDocument);
 * console.log(result.result);
 * ```
 */
import { RLMConfig, RLMResult, RLMStats, TraceEvent, FileStorageConfig, ContextOverflowConfig } from './bridge-interface';
import { BridgeType } from './bridge-factory';
import { z } from 'zod';
import { StructuredRLMResult } from './structured-types';
import { FileStorageResult } from './file-storage';
import { RLMEventType, RLMEventMap } from './events';
import { CacheConfig } from './cache';
import { RetryConfig } from './retry';
import { RLMStream, StreamOptions } from './streaming';
import { RLMExtendedConfig, ValidationResult } from './config';
/** Extended result with cache information */
export interface RLMCompletionResult extends RLMResult {
    /** Whether this result was served from cache */
    cached: boolean;
    /** Model that was actually used (relevant with fallback) */
    model: string;
}
/** Pretty-printable result wrapper */
export declare class RLMResultFormatter {
    readonly result: string;
    readonly stats: RLMStats;
    readonly cached: boolean;
    readonly model: string;
    readonly trace_events?: TraceEvent[] | undefined;
    constructor(result: string, stats: RLMStats, cached: boolean, model: string, trace_events?: TraceEvent[] | undefined);
    /** Format stats as a concise one-liner */
    prettyStats(): string;
    /** Serialize to a JSON-safe object */
    toJSON(): Record<string, unknown>;
    /** Format as Markdown */
    toMarkdown(): string;
}
/**
 * Fluent builder for configuring RLM instances.
 *
 * @example
 * ```typescript
 * const rlm = RLM.builder('gpt-4o-mini')
 *   .maxDepth(10)
 *   .withMetaAgent()
 *   .withDebug()
 *   .withCache({ strategy: 'exact' })
 *   .withRetry({ maxRetries: 3 })
 *   .build();
 * ```
 */
export declare class RLMBuilder {
    private model;
    private config;
    private bridgeType;
    constructor(model: string);
    /** Set the API key */
    apiKey(key: string): this;
    /** Set the API base URL */
    apiBase(url: string): this;
    /** Set maximum recursion depth */
    maxDepth(depth: number): this;
    /** Set maximum iterations */
    maxIterations(iterations: number): this;
    /** Enable meta-agent query optimization */
    withMetaAgent(config?: {
        model?: string;
        max_optimize_len?: number;
    }): this;
    /** Enable debug mode */
    withDebug(logOutput?: string): this;
    /** Configure observability */
    withObservability(config: RLMConfig['observability']): this;
    /** Configure caching */
    withCache(config?: CacheConfig): this;
    /** Configure retry behavior */
    withRetry(config?: RetryConfig): this;
    /** Configure fallback models */
    withFallback(models: string[]): this;
    /** Set the bridge type */
    bridge(type: BridgeType): this;
    /** Configure context overflow recovery */
    withContextOverflow(config?: ContextOverflowConfig): this;
    /** Set the Go binary path */
    binaryPath(path: string): this;
    /** Add LiteLLM passthrough parameters */
    litellmParams(params: Record<string, unknown>): this;
    /** Build the RLM instance */
    build(): RLM;
}
export declare class RLM {
    private bridge;
    private model;
    private rlmConfig;
    private bridgeType;
    private lastTraceEvents;
    private events;
    private cache;
    /**
     * Create a new RLM instance.
     *
     * @param model - The LLM model identifier (e.g., 'gpt-4o-mini', 'claude-sonnet-4-20250514')
     * @param rlmConfig - Configuration options for the RLM engine
     * @param bridgeType - Bridge selection: 'go' (default)
     *
     * @example
     * ```typescript
     * const rlm = new RLM('gpt-4o-mini', {
     *   api_key: process.env.OPENAI_API_KEY,
     *   max_depth: 5,
     *   cache: { enabled: true },
     *   retry: { maxRetries: 3 },
     * });
     * ```
     */
    constructor(model: string, rlmConfig?: RLMExtendedConfig, bridgeType?: BridgeType);
    /**
     * Create an RLM instance using environment variables for configuration.
     *
     * @param model - The LLM model identifier
     * @returns RLM instance configured from environment
     *
     * @example
     * ```typescript
     * // Uses OPENAI_API_KEY from environment
     * const rlm = RLM.fromEnv('gpt-4o-mini');
     * ```
     */
    static fromEnv(model: string): RLM;
    /**
     * Create an RLM instance with debug logging enabled.
     *
     * @param model - The LLM model identifier
     * @param config - Additional configuration options
     * @returns RLM instance with debug mode active
     */
    static withDebug(model: string, config?: RLMExtendedConfig): RLM;
    /**
     * Create an RLM instance configured for Azure OpenAI.
     *
     * @param deploymentName - Azure deployment name
     * @param config - Azure-specific configuration
     * @returns RLM instance configured for Azure
     */
    static forAzure(deploymentName: string, config: {
        apiBase: string;
        apiKey?: string;
        apiVersion?: string;
    }): RLM;
    /**
     * Create a fluent builder for advanced configuration.
     *
     * @param model - The LLM model identifier
     * @returns Builder instance
     *
     * @example
     * ```typescript
     * const rlm = RLM.builder('gpt-4o-mini')
     *   .apiKey(process.env.OPENAI_API_KEY!)
     *   .maxDepth(10)
     *   .withMetaAgent()
     *   .withCache({ strategy: 'exact' })
     *   .build();
     * ```
     */
    static builder(model: string): RLMBuilder;
    private normalizeConfig;
    private ensureBridge;
    /**
     * Register an event listener.
     *
     * @param event - Event type to listen for
     * @param listener - Callback function
     *
     * @example
     * ```typescript
     * rlm.on('llm_call', (e) => console.log(`Calling ${e.model}`));
     * rlm.on('error', (e) => reportError(e.error));
     * rlm.on('cache', (e) => console.log(`Cache ${e.action}`));
     * ```
     */
    on<K extends RLMEventType>(event: K, listener: (event: RLMEventMap[K]) => void): this;
    /**
     * Register a one-time event listener.
     *
     * @param event - Event type to listen for
     * @param listener - Callback function (called once then removed)
     */
    once<K extends RLMEventType>(event: K, listener: (event: RLMEventMap[K]) => void): this;
    /**
     * Remove an event listener.
     *
     * @param event - Event type
     * @param listener - The listener function to remove
     */
    off<K extends RLMEventType>(event: K, listener: (event: RLMEventMap[K]) => void): this;
    /** Remove all event listeners */
    removeAllListeners(event?: RLMEventType): this;
    /**
     * Execute a completion against an LLM with recursive decomposition.
     *
     * @param query - The question or instruction for the LLM
     * @param context - The document or data to process (can be very large)
     * @param options - Optional completion settings
     * @returns The LLM response with execution statistics
     *
     * @example
     * ```typescript
     * const result = await rlm.completion('Summarize the key points', longDocument);
     * console.log(result.result);
     * console.log(`Used ${result.stats.llm_calls} LLM calls`);
     * ```
     */
    completion(query: string, context: string, options?: {
        signal?: AbortSignal;
    }): Promise<RLMCompletionResult>;
    /**
     * Extract structured, typed data from context using a Zod schema.
     *
     * @param query - The extraction task to perform
     * @param context - The document or data to process
     * @param schema - Zod schema defining the expected output structure
     * @param options - Execution options (parallelExecution, maxRetries, signal)
     * @returns Typed result matching your Zod schema
     *
     * @example
     * ```typescript
     * const schema = z.object({
     *   summary: z.string(),
     *   score: z.number().min(1).max(10),
     *   tags: z.array(z.string()),
     * });
     *
     * const result = await rlm.structuredCompletion('Analyze this document', doc, schema);
     * console.log(result.result.summary);  // string
     * console.log(result.result.score);    // number
     * console.log(result.result.tags);     // string[]
     * ```
     */
    structuredCompletion<T>(query: string, context: string, schema: z.ZodSchema<T>, options?: {
        maxRetries?: number;
        parallelExecution?: boolean;
        signal?: AbortSignal;
    }): Promise<StructuredRLMResult<T>>;
    /**
     * Stream a completion with progressive text output.
     *
     * Returns an async iterable of stream chunks. Supports AbortController
     * for cancellation.
     *
     * Note: Currently simulates streaming by chunking the full response.
     * Full streaming support (from the Go binary) is planned.
     *
     * @param query - The question or instruction for the LLM
     * @param context - The document or data to process
     * @param options - Stream options including AbortController signal
     * @returns Async iterable stream of chunks
     *
     * @example
     * ```typescript
     * const stream = rlm.streamCompletion(query, context);
     * for await (const chunk of stream) {
     *   if (chunk.type === 'text') process.stdout.write(chunk.text);
     * }
     *
     * // Or collect as string
     * const text = await rlm.streamCompletion(query, context).toText();
     *
     * // With abort
     * const controller = new AbortController();
     * const stream = rlm.streamCompletion(query, context, { signal: controller.signal });
     * setTimeout(() => controller.abort(), 5000);
     * ```
     */
    streamCompletion(query: string, context: string, options?: StreamOptions): RLMStream;
    /**
     * Stream a structured completion with partial object updates.
     *
     * @param query - The extraction task to perform
     * @param context - The document or data to process
     * @param schema - Zod schema for the output structure
     * @param options - Stream and execution options
     * @returns Async iterable stream with partial object chunks
     */
    streamStructuredCompletion<T>(query: string, context: string, schema: z.ZodSchema<T>, options?: StreamOptions & {
        maxRetries?: number;
        parallelExecution?: boolean;
    }): RLMStream<T>;
    /**
     * Execute multiple completions in parallel with concurrency control.
     *
     * @param queries - Array of query+context pairs to process
     * @param options - Batch options including concurrency limit
     * @returns Array of results in the same order as input
     *
     * @example
     * ```typescript
     * const results = await rlm.batchCompletion([
     *   { query: 'Summarize chapter 1', context: ch1 },
     *   { query: 'Summarize chapter 2', context: ch2 },
     *   { query: 'Summarize chapter 3', context: ch3 },
     * ], { concurrency: 2 });
     * ```
     */
    batchCompletion(queries: Array<{
        query: string;
        context: string;
    }>, options?: {
        concurrency?: number;
        signal?: AbortSignal;
    }): Promise<Array<RLMCompletionResult | Error>>;
    /**
     * Execute multiple structured completions in parallel.
     *
     * @param queries - Array of query+context+schema triples
     * @param options - Batch options including concurrency limit
     * @returns Array of typed results
     */
    batchStructuredCompletion<T>(queries: Array<{
        query: string;
        context: string;
        schema: z.ZodSchema<T>;
    }>, options?: {
        concurrency?: number;
        signal?: AbortSignal;
    }): Promise<Array<StructuredRLMResult<T> | Error>>;
    /**
     * Run a completion using files from a folder (local or S3) as context.
     *
     * @param query - The question or task to perform
     * @param fileConfig - File storage configuration (local path or S3 bucket)
     * @returns Result with fileStorage metadata (files included, skipped, total size)
     *
     * @example
     * ```typescript
     * const result = await rlm.completionFromFiles(
     *   'Summarize the architecture',
     *   { type: 'local', path: './src', extensions: ['.ts'] }
     * );
     * console.log(result.result);
     * console.log(`Processed ${result.fileStorage.files.length} files`);
     * ```
     */
    completionFromFiles(query: string, fileConfig: FileStorageConfig): Promise<RLMCompletionResult & {
        fileStorage: FileStorageResult;
    }>;
    /**
     * Run a structured completion using files from a folder (local or S3) as context.
     *
     * @param query - The extraction task to perform
     * @param fileConfig - File storage configuration
     * @param schema - Zod schema for the output structure
     * @param options - Execution options
     * @returns Typed result with fileStorage metadata
     */
    structuredCompletionFromFiles<T>(query: string, fileConfig: FileStorageConfig, schema: z.ZodSchema<T>, options?: {
        maxRetries?: number;
        parallelExecution?: boolean;
    }): Promise<StructuredRLMResult<T> & {
        fileStorage: FileStorageResult;
    }>;
    /**
     * Preview which files would be included from a file storage config
     * without actually reading them. Useful for dry-runs.
     *
     * @param fileConfig - File storage configuration
     * @returns Array of relative file paths that match the config
     */
    previewFiles(fileConfig: FileStorageConfig): Promise<string[]>;
    /**
     * Build context from a file storage config without running a completion.
     * Useful for inspecting the generated context string.
     *
     * @param fileConfig - File storage configuration
     * @returns Built context with metadata
     */
    buildFileContext(fileConfig: FileStorageConfig): Promise<FileStorageResult>;
    /**
     * Returns trace events from the last operation.
     * Only populated when observability is enabled in the config.
     *
     * @returns Array of trace events from the most recent completion
     */
    getTraceEvents(): TraceEvent[];
    /**
     * Get cache statistics (hits, misses, hit rate).
     *
     * @returns Cache performance statistics
     */
    getCacheStats(): import("./cache").CacheStats;
    /** Clear the completion cache */
    clearCache(): void;
    /**
     * Validate the current configuration without making any API calls.
     * Checks binary existence, config validity, and connectivity hints.
     *
     * @returns Validation result with issues
     *
     * @example
     * ```typescript
     * const issues = rlm.validate();
     * if (!issues.valid) {
     *   console.error('Config issues:', issues.issues);
     * }
     * ```
     */
    validate(): ValidationResult;
    /**
     * Create a formatted result wrapper from a completion result.
     *
     * @param result - The completion result to format
     * @returns Formatter with prettyStats(), toJSON(), and toMarkdown() methods
     */
    formatResult(result: RLMCompletionResult): RLMResultFormatter;
    /**
     * Clean up the bridge connection and free resources.
     * Call this when you're done using the RLM instance.
     */
    cleanup(): Promise<void>;
    /**
     * Support for `Symbol.asyncDispose` (Node 22+ `await using`).
     */
    [Symbol.asyncDispose](): Promise<void>;
    private zodToJsonSchema;
}