import { AppError } from '../utils/errors.js';
/**
 * Embedder configuration
 */
export interface EmbedderConfig {
    /** HuggingFace model path */
    modelPath: string;
    /** Batch size */
    batchSize: number;
    /** Model cache directory */
    cacheDir: string;
    /** Device type */
    device?: string;
    /**
     * Quantization dtype, passed through to transformers.js with no allowlist.
     * `undefined` means unset, which `initialize()` resolves to fp32 — the
     * distinction gates failure-path error enrichment, so keep it.
     */
    dtype?: string;
    /**
     * Embed document chunks behind a `Title:` line naming their document
     * (default: false). Read by ingestion, which builds the embedding input.
     */
    titlePrefix?: boolean;
    /** Add section paths to chunk embeddings when they fit (default: false). */
    headingPrefix?: boolean;
}
/** Selects the model's prompt; omitted means its default prompt. */
export type EmbeddingRole = 'query' | 'document';
interface TokenizerOptions {
    padding?: boolean;
    truncation?: boolean;
    return_tensor?: boolean;
    max_length?: number;
}
export interface PipelineTokenizer {
    (input: string[], options: TokenizerOptions): {
        input_ids?: unknown;
    } | null | undefined;
    /** `unknown` because a model may omit it or report a sentinel; see {@link usableTokenLimit}. */
    model_max_length?: unknown;
}
export interface EmbeddingComputationIdentity {
    fingerprint: string;
    dimension: number;
}
export interface TokenLimitClamp {
    /** The effective token cap, or `null` for degraded mode (no cap, no clamp). */
    tokenLimit: number | null;
    /** The pre-clamp tokenizer, for measuring true lengths. */
    measurementTokenizer: PipelineTokenizer | null;
}
/**
 * Bound the pipeline's tokenization length to the model's position window, by
 * installing a proxy on `candidate`'s tokenizer.
 *
 * The pipeline tokenizes with no `max_length`, which resolves to
 * `model_max_length ?? Infinity` and then to the batch's longest sequence, so a
 * model whose `tokenizer_config.json` omits a real limit sends more positions
 * than it has position embeddings and onnxruntime fails in the
 * position-embedding `Add` node (#202).
 *
 * The measurement tokenizer is captured before the proxy, so measurement
 * reports true lengths. A `Proxy` is used because `model_max_length` is a getter
 * with no setter. An unrecognized shape, or no usable limit, leaves `candidate`
 * untouched.
 */
export declare function installTokenLimitClamp(candidate: unknown): TokenLimitClamp;
/**
 * Embedding generation error
 */
export declare class EmbeddingError extends AppError {
    constructor(message: string, options?: {
        cause?: Error;
    });
}
/** Transformers.js wrapper: lazily loaded model, batched embedding. */
export declare class Embedder {
    private model;
    private initPromise;
    /** The resolved cap, or `null` before initialization and in degraded mode. */
    private tokenLimit;
    /** The pre-clamp tokenizer, so measurement never reports clamped lengths. */
    private measurementTokenizer;
    /**
     * One-shot flags, per instance: each state belongs to this embedder's model.
     * They survive `dispose()`; re-initialization is not new information.
     */
    private truncationWarned;
    private degradedModeWarned;
    private prompts;
    private warnings;
    private readonly config;
    private computationIdentityPromise;
    constructor(config: EmbedderConfig);
    get headingPrefix(): boolean;
    get titlePrefix(): boolean;
    /** Model settings this tool cannot honor; empty until the model loads. */
    get modelWarnings(): readonly string[];
    /**
     * Release resources held by the Embedder pipeline
     */
    dispose(): Promise<void>;
    /**
     * Initialize Transformers.js model
     */
    initialize(): Promise<void>;
    /**
     * Best-effort failure-path enrichment for an explicit `RAG_DTYPE`: name the
     * dtypes the model does provide when the requested one is absent.
     *
     * The enumeration is a Hub network call in its own try/catch, so an
     * air-gapped run degrades to a generic dtype-aware message instead of
     * surfacing a confusing secondary error. Never throws, and never converts
     * the load failure into a fallback — the caller always re-throws.
     */
    private enrichDtypeFailureMessage;
    /**
     * Ensure model is initialized (lazy initialization)
     * This method is called automatically by embed() and embedBatch()
     */
    private ensureInitialized;
    /** Identity of the loaded embedding function, or `null` when local assets cannot be proven. */
    getComputationIdentity(): Promise<EmbeddingComputationIdentity | null>;
    private createComputationIdentity;
    private hashModelAssets;
    private captureModelAssetSnapshot;
    private resolveAssetPath;
    /**
     * The effective token cap, or `null` when none could be resolved.
     *
     * Self-initializing: the value exists only after the model loads, and a
     * caller may need it before the first embedding.
     */
    getTokenLimit(): Promise<number | null>;
    /**
     * Report once that no cap was resolved. Warning here rather than in
     * `initialize()` covers every consumer, which all read the cap through
     * {@link getTokenLimit}.
     */
    private warnDegradedMode;
    /**
     * The lengths batch planning runs on: `min(trueLength, cap)`, the length the
     * clamped pipeline actually feeds the model. Warns once when a true length
     * exceeds the cap.
     */
    private planTokenLengths;
    /**
     * The true token length of each text as embedded for `role`, prompt
     * included, in input order. Tokenization only, no inference.
     *
     * Measured with `truncation: false` through the pre-clamp tokenizer, so a
     * length above {@link getTokenLimit} means inference will truncate. Throws
     * when no such tokenizer was captured, rather than returning a length
     * measured through an unknown surface.
     */
    countTokens(texts: string[], role?: EmbeddingRole): Promise<number[]>;
    /** The prompt this model's config sets for documents, or `''`. */
    getDocumentPrompt(): Promise<string>;
    private withPrompt;
    /** Measures `texts` as given; each caller applies the prompt exactly once. */
    private measureTokens;
    /**
     * Single-text embedding; the vector dimension depends on the model.
     *
     * Delegates to {@link embedBatch} so this path shares its clamp, measurement
     * and warning rather than reaching the pipeline unguarded.
     */
    embed(text: string, role?: EmbeddingRole): Promise<number[]>;
    /** Batched embedding; the vector dimension depends on the model. */
    embedBatch(texts: string[], role?: EmbeddingRole): Promise<number[][]>;
}
export {};
//# sourceMappingURL=index.d.ts.map