import { Chunk } from './chunking.js';

/**
 * Semantic Chunking with Smoothing-Based Topic Boundaries (Issue #368)
 *
 * An optional alternative to the recursive chunker in chunking.ts.
 * Uses sentence embeddings + cosine similarity + smoothing to detect
 * natural topic boundaries, producing more coherent chunks.
 */

interface SemanticChunkingConfig {
    /** Target tokens per chunk. Default: 200. */
    targetTokens: number;
    /** Minimum tokens for a segment before merging with neighbor. Default: 100. */
    minTokens: number;
    /** Maximum tokens for a segment before recursive splitting. Default: 400. */
    maxTokens: number;
    /** Window size for the moving-average smoothing filter. Default: 3. */
    smoothingWindowSize: number;
    /** How many standard deviations below the mean constitutes a boundary. Default: 1.0. */
    boundaryThresholdStdDevs: number;
    /** Batch size for embedding requests. Default: 32. */
    embeddingBatchSize: number;
    /** Fall back to recursive chunking when embeddings are unavailable. Default: true. */
    fallbackToRecursive: boolean;
}
declare const DEFAULT_SEMANTIC_CHUNKING_CONFIG: SemanticChunkingConfig;
interface SemanticChunk extends Chunk {
    /** Optional topic hint derived from position. */
    topicLabel?: string;
    /** Cosine similarity score at the trailing boundary of this chunk. */
    boundaryScore: number;
}
interface SemanticChunkResult {
    /** Whether content was split into multiple chunks. */
    chunked: boolean;
    /** The chunks produced. */
    chunks: SemanticChunk[];
    /** Sentence indices where topic splits occurred. */
    boundaries: number[];
    /** Which algorithm produced the result. */
    method: "semantic" | "recursive-fallback";
}
/** Caller-provided function that embeds an array of texts, returning vectors. */
type EmbedFn = (texts: string[]) => Promise<number[][]>;
/**
 * Cosine similarity between two vectors.
 * Returns a value in [-1, 1]. Identical direction = 1, orthogonal = 0.
 *
 * NOTE: This duplicates cosineSimilarity in recall-mmr.ts and embedding-fallback.ts.
 * Consider extracting to a shared math utility in a future refactor.
 */
declare function cosineSimilarity(a: number[], b: number[]): number;
/**
 * Arithmetic mean of a numeric series.
 */
declare function mean(series: number[]): number;
/**
 * Population standard deviation of a numeric series.
 */
declare function stddev(series: number[]): number;
/**
 * Simple moving average over a 1D series.
 * The window is centered: for window size W, each output[i] averages
 * series[i - floor(W/2) .. i + floor(W/2)], clamped to bounds.
 *
 * Even window sizes are rounded up to the next odd value so the window
 * is symmetric around the center point (Finding 4, PR #420).
 */
declare function movingAverage(series: number[], windowSize: number): number[];
/**
 * Find indices in the series that are local minima AND below the threshold.
 * A local minimum is a point lower than both its immediate neighbors
 * (or lower-or-equal at series boundaries).
 */
declare function findLocalMinima(series: number[], threshold: number): number[];
/**
 * Semantic chunking with smoothing-based topic boundary detection.
 *
 * @param content   - Full text to chunk.
 * @param embedFn   - Async function that embeds an array of texts.
 * @param config    - Optional partial config overrides.
 * @returns SemanticChunkResult
 */
declare function semanticChunkContent(content: string, embedFn: EmbedFn, config?: Partial<SemanticChunkingConfig>): Promise<SemanticChunkResult>;

export { DEFAULT_SEMANTIC_CHUNKING_CONFIG, type EmbedFn, type SemanticChunk, type SemanticChunkResult, type SemanticChunkingConfig, cosineSimilarity, findLocalMinima, mean, movingAverage, semanticChunkContent, stddev };
