/**
 * Brain Embedding System
 *
 * Provides text-to-vector embedding for semantic search in brain.db.
 * Uses a pluggable provider interface — real model integration
 * (e.g. @huggingface/transformers with all-MiniLM-L6-v2) is separate
 * from the embedding pipeline. When no provider is set, the system
 * falls back to FTS5-only search gracefully.
 *
 * @epic T5149
 * @task T5386
 */
/** Contract for embedding providers (local models, API services, etc.). */
export interface EmbeddingProvider {
    /** Convert text into a fixed-dimension float vector. */
    embed(text: string): Promise<Float32Array>;
    /** Number of dimensions the provider produces. Must match vec0 table. */
    readonly dimensions: number;
    /**
     * Model identity stored beside every vector: `<model id>@<revision>:<dtype>`.
     * Vectors are only ever compared with vectors of the same model, and a
     * stored vector of any other model is re-embedded by the backfill (T13740).
     */
    readonly model: string;
    /**
     * Whether the provider CAN produce embeddings — capability, not state.
     *
     * Implementations MUST NOT return "has already produced one": a provider
     * that reports unavailable until it has embedded something can never be
     * asked to embed anything, because every caller checks this first. That
     * deadlock made local embeddings entirely inert (gh#1217). A provider whose
     * model loads lazily is AVAILABLE before the first load; it becomes
     * unavailable only once loading has actually failed.
     */
    isAvailable(): boolean;
}
/** Matches the brain_embeddings vec0 table: FLOAT[384]. */
export declare const EMBEDDING_DIMENSIONS = 384;
/**
 * Register an embedding provider for the brain system.
 * Validates that the provider's dimensions match the vec0 table.
 *
 * @throws Error if provider dimensions do not match EMBEDDING_DIMENSIONS
 */
export declare function setEmbeddingProvider(provider: EmbeddingProvider): void;
/** Get the currently registered embedding provider, or null. */
export declare function getEmbeddingProvider(): EmbeddingProvider | null;
/** Clear the current embedding provider (useful for testing). */
export declare function clearEmbeddingProvider(): void;
/**
 * Embed text into a float vector using the registered provider.
 * Returns null when no provider is set or not available (FTS5-only fallback).
 */
export declare function embedText(text: string): Promise<Float32Array | null>;
/**
 * Check whether embedding is available — i.e. a provider is registered and
 * has not failed to load.
 *
 * This is a CAPABILITY check. It is deliberately true before the first
 * embedding is produced: gating the only call that can warm a lazy provider on
 * that provider already being warm is the gh#1217 deadlock.
 */
export declare function isEmbeddingAvailable(): boolean;
/**
 * Initialize the default local embedding provider.
 *
 * Loads the LocalEmbeddingProvider dynamically and registers it via
 * setEmbeddingProvider(). Should be called once at startup when
 * `brain.embedding.enabled` is true.
 *
 * Uses dynamic import to avoid loading the heavy @huggingface/transformers
 * bundle unless embedding is actually requested.
 *
 * @task T136 @epic T134
 */
export declare function initDefaultProvider(): Promise<void>;
/**
 * Register the default provider if nothing has registered one yet.
 *
 * ## Why a consumer must ask rather than assume (T12314)
 *
 * Registration is scheduled by a `setImmediate` in the brain DB open path and
 * its failures are swallowed, so a consumer that asks
 * {@link isEmbeddingAvailable} can legitimately be told "no" for two unrelated
 * reasons: the provider failed, or it simply has not been registered yet. For
 * as long as the availability check was unsatisfiable (T12129) that difference
 * could not be observed. With the deadlock gone it is the whole story —
 * measured against the installed 2026.9.14, the provider was absent at import,
 * and registering it explicitly took **0 ms** and then produced a real
 * 384-dimension vector.
 *
 * Registration is therefore free: the ~22 MB model download happens on the
 * first {@link embedText}, not here. There is no cost argument for making a
 * consumer race a deferred registration it cannot see.
 *
 * @param projectRoot - Project whose config decides `brain.embedding.enabled`.
 * @returns `true` when a provider is registered once this resolves, and
 *   `false` when `brain.embedding.enabled` is false (T13716).
 * @remarks A load failure is NOT hidden — the provider registers, and its
 * subsequent failure latches and is reported by the consumer. Returning
 * `false` here means no provider could be constructed at all.
 * @example
 * ```ts
 * if (!(await ensureEmbeddingProvider())) reportUnavailable();
 * ```
 */
export declare function ensureEmbeddingProvider(projectRoot?: string): Promise<boolean>;
//# sourceMappingURL=brain-embedding.d.ts.map