/// Persistence interface for the trainer's knowledge base.
///
/// The implementation splits raw text into chunks, generates embeddings
/// via the Nomic server, stores them in the local database, and provides
/// semantic search for RAG context injection.
abstract class NoteRepository {
  /// Splits [text] into overlapping chunks, generates an embedding for each,
  /// and persists them under a shared [sourceId].
  Future<void> addNote(String text);

  /// Returns the [topK] most semantically similar chunk texts for [query].
  /// Returns an empty list if no chunks are stored or the embedding server
  /// is unavailable.
  Future<List<String>> searchSimilar(String query, {int topK = 3});

  /// Returns the total number of stored chunks.
  Future<int> getChunkCount();

  /// Deletes every stored chunk (full knowledge-base reset).
  Future<void> clearAll();
}