namespace Api.Services.Contracts;

/// <summary>
/// Splits document text into overlapping chunks suitable for embedding and vector search.
/// </summary>
public interface ITextChunker
{
    /// <summary>
    /// Divides <paramref name="text"/> into a list of chunks using a sliding window.
    /// Adjacent chunks share <paramref name="overlap"/> characters to preserve cross-boundary context.
    /// </summary>
    /// <param name="text">The full document text to chunk.</param>
    /// <param name="chunkSize">Maximum character length per chunk (clamped to 300–3000).</param>
    /// <param name="overlap">Number of trailing characters from the previous chunk to repeat at the start of the next (clamped to 0–chunkSize/2).</param>
    /// <returns>Ordered list of non-empty text chunks.</returns>
    IReadOnlyList<string> Chunk(string text, int chunkSize, int overlap);
}