refactor: introduce backend-neutral embedding store interface

Author: matthiasn

CHANGELOG.md

@@ -10,6 +10,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   one at a time. Includes Select All / Unselect All toggle.
 - Vector search now available on the journal tab (previously tasks-only).
 
+### Changed
+- Refactored the embedding pipeline behind a backend-neutral store interface to
+  prepare alternate vector backends without another large call-site migration.
+
 ### Removed
 - Removed "Re-index All Embeddings" maintenance action (superseded by
   multi-category generate).

flatpak/com.matthiasn.lotti.metainfo.xml

@@ -34,6 +34,7 @@
     <release version="0.9.905" date="2026-03-06">
       <description>
           <p>Unified embedding generation: select multiple categories at once with a Select All toggle. Vector search is now available on the journal tab alongside tasks. Removed the separate "Re-index All Embeddings" action.</p>
+          <p>Refactored the embedding pipeline behind a backend-neutral store interface to prepare alternate vector backends without another large call-site migration.</p>
       </description>
     </release>
     <release version="0.9.904" date="2026-03-06">

lib/features/agents/state/agent_providers.dart

@@ -22,7 +22,7 @@ import 'package:lotti/features/agents/workflow/improver_agent_workflow.dart';
 import 'package:lotti/features/agents/workflow/task_agent_workflow.dart';
 import 'package:lotti/features/agents/workflow/template_evolution_workflow.dart';
 import 'package:lotti/features/ai/conversation/conversation_repository.dart';
-import 'package:lotti/features/ai/database/embeddings_db.dart';
+import 'package:lotti/features/ai/database/embedding_store.dart';
 import 'package:lotti/features/ai/repository/ai_config_repository.dart';
 import 'package:lotti/features/ai/repository/ai_input_repository.dart';
 import 'package:lotti/features/ai/repository/cloud_inference_repository.dart';
@@ -742,8 +742,8 @@ Future<List<AgentDomainEntity>> evolutionNotes(
 TaskAgentWorkflow taskAgentWorkflow(Ref ref) {
   // Embedding dependencies are optional — the pipeline may not be available
   // (e.g. missing native sqlite-vec library on CI).
-  final embeddingsDb = getIt.isRegistered<EmbeddingsDb>()
-      ? getIt<EmbeddingsDb>()
+  final embeddingStore = getIt.isRegistered<EmbeddingStore>()
+      ? getIt<EmbeddingStore>()
       : null;
   final embeddingRepository = getIt.isRegistered<OllamaEmbeddingRepository>()
       ? getIt<OllamaEmbeddingRepository>()
@@ -762,7 +762,7 @@ TaskAgentWorkflow taskAgentWorkflow(Ref ref) {
     syncService: ref.watch(agentSyncServiceProvider),
     templateService: ref.watch(agentTemplateServiceProvider),
     domainLogger: ref.watch(domainLoggerProvider),
-    embeddingsDb: embeddingsDb,
+    embeddingStore: embeddingStore,
     embeddingRepository: embeddingRepository,
   );
 }

lib/features/agents/state/agent_providers.g.dart

@@ -24,7 +24,7 @@ import 'package:lotti/features/agents/workflow/task_tool_dispatcher.dart';
 import 'package:lotti/features/agents/workflow/wake_result.dart';
 import 'package:lotti/features/ai/conversation/conversation_manager.dart';
 import 'package:lotti/features/ai/conversation/conversation_repository.dart';
-import 'package:lotti/features/ai/database/embeddings_db.dart';
+import 'package:lotti/features/ai/database/embedding_store.dart';
 import 'package:lotti/features/ai/model/inference_usage.dart';
 import 'package:lotti/features/ai/repository/ai_config_repository.dart';
 import 'package:lotti/features/ai/repository/ai_input_repository.dart';
@@ -76,7 +76,7 @@ class TaskAgentWorkflow {
     required this.syncService,
     required this.templateService,
     this.domainLogger,
-    this.embeddingsDb,
+    this.embeddingStore,
     this.embeddingRepository,
   });
 
@@ -101,7 +101,7 @@ class TaskAgentWorkflow {
   /// Optional embedding dependencies. When both are provided, agent reports
   /// are embedded for vector search after persistence. The pipeline is
   /// non-essential — if unavailable, reports are still persisted normally.
-  final EmbeddingsDb? embeddingsDb;
+  final EmbeddingStore? embeddingStore;
   final OllamaEmbeddingRepository? embeddingRepository;
 
   static const _uuid = Uuid();
@@ -672,9 +672,9 @@ class TaskAgentWorkflow {
     required String taskId,
     String? previousReportId,
   }) async {
-    final db = embeddingsDb;
+    final store = embeddingStore;
     final repo = embeddingRepository;
-    if (db == null || repo == null) return;
+    if (store == null || repo == null) return;
 
     try {
       final baseUrl = await aiConfigRepository.resolveOllamaBaseUrl();
@@ -690,7 +690,7 @@ class TaskAgentWorkflow {
         taskId: taskId,
         categoryId: categoryId,
         subtype: AgentReportScopes.current,
-        embeddingsDb: db,
+        embeddingStore: store,
         embeddingRepository: repo,
         baseUrl: baseUrl,
       );
@@ -699,7 +699,7 @@ class TaskAgentWorkflow {
       // so we don't lose search coverage if the embedding call fails or
       // the content is too short.
       if (didEmbed && previousReportId != null) {
-        db.deleteEntityEmbeddings(previousReportId);
+        store.deleteEntityEmbeddings(previousReportId);
       }
     } catch (e, s) {
       _logError('failed to embed agent report', error: e, stackTrace: s);

lib/features/agents/workflow/task_agent_workflow.dart

@@ -16,6 +16,14 @@ The AI feature consists of several key components:
 8. **Automatic Setup**: Model pre-population and intelligent defaults
 9. **Error Recovery**: Comprehensive error handling and user-friendly messages
 
+## Embedding Search
+
+The AI feature also owns the local embedding pipeline used for semantic search.
+
+- **`database/embedding_store.dart`** defines the backend-neutral `EmbeddingStore` contract used by services, repositories, and maintenance UI.
+- **`database/sqlite_embedding_store.dart`** adapts the existing sqlite-vec `EmbeddingsDb` to that contract.
+- Higher-level code depends on `EmbeddingStore`, not directly on sqlite-vec internals, so the vector backend can be swapped in a future change without another large call-site migration.
+
 ## Architecture
 
 ### Core Components

lib/features/ai/README.md

@@ -0,0 +1,71 @@
+import 'dart:typed_data';
+
+/// The fixed embedding dimension used by the current embedding model.
+const kEmbeddingDimensions = 1024;
+
+/// Result of a vector similarity search.
+class EmbeddingSearchResult {
+  const EmbeddingSearchResult({
+    required this.entityId,
+    required this.distance,
+    required this.entityType,
+    this.chunkIndex = 0,
+    this.taskId = '',
+    this.subtype = '',
+  });
+
+  final String entityId;
+  final double distance;
+  final String entityType;
+
+  /// The zero-based chunk index within the source entity.
+  ///
+  /// For short content that fits in a single chunk this is 0.
+  /// For chunked content this identifies which segment matched.
+  final int chunkIndex;
+
+  /// The task ID this embedding relates to, for direct lookup.
+  ///
+  /// Populated for agent report embeddings to link back to the parent task.
+  /// Empty string when not applicable.
+  final String taskId;
+
+  /// The subtype of the embedding, e.g. agent template name.
+  ///
+  /// Used to distinguish between multiple agent reports for the same task.
+  /// Empty string when not applicable.
+  final String subtype;
+}
+
+/// Backend-neutral store for derived vector embeddings.
+abstract class EmbeddingStore {
+  String? getContentHash(String entityId);
+
+  bool hasEmbedding(String entityId);
+
+  int get count;
+
+  void replaceEntityEmbeddings({
+    required String entityId,
+    required String entityType,
+    required String modelId,
+    required String contentHash,
+    required List<Float32List> embeddings,
+    String categoryId = '',
+    String taskId = '',
+    String subtype = '',
+  });
+
+  void deleteEntityEmbeddings(String entityId);
+
+  List<EmbeddingSearchResult> search({
+    required Float32List queryVector,
+    int k = 10,
+    String? entityTypeFilter,
+    Set<String>? categoryIds,
+  });
+
+  void deleteAll();
+
+  void close();
+}

lib/features/ai/database/embedding_store.dart

@@ -1,46 +1,11 @@
 import 'dart:typed_data';
 
 import 'package:clock/clock.dart';
+import 'package:lotti/features/ai/database/embedding_store.dart';
 import 'package:sqlite3/sqlite3.dart';
 
-/// The fixed embedding dimension used by the vec0 virtual table.
-///
-/// This must match the `float[N]` declaration in the vec0 schema.
-const kEmbeddingDimensions = 1024;
-
-/// Result of a vector similarity search.
-class EmbeddingSearchResult {
-  const EmbeddingSearchResult({
-    required this.entityId,
-    required this.distance,
-    required this.entityType,
-    this.chunkIndex = 0,
-    this.taskId = '',
-    this.subtype = '',
-  });
-
-  final String entityId;
-  final double distance;
-  final String entityType;
-
-  /// The zero-based chunk index within the source entity.
-  ///
-  /// For short content that fits in a single chunk this is 0.
-  /// For chunked content this identifies which segment matched.
-  final int chunkIndex;
-
-  /// The task ID this embedding relates to, for direct lookup.
-  ///
-  /// Populated for agent report embeddings to link back to the parent task.
-  /// Empty string when not applicable.
-  final String taskId;
-
-  /// The subtype of the embedding, e.g. agent template name.
-  ///
-  /// Used to distinguish between multiple agent reports for the same task.
-  /// Empty string when not applicable.
-  final String subtype;
-}
+export 'package:lotti/features/ai/database/embedding_store.dart'
+    show EmbeddingSearchResult, kEmbeddingDimensions;
 
 /// Standalone vector-embedding database backed by sqlite-vec.
 ///

lib/features/ai/database/embeddings_db.dart

@@ -0,0 +1,72 @@
+import 'dart:typed_data';
+
+import 'package:lotti/features/ai/database/embedding_store.dart';
+import 'package:lotti/features/ai/database/embeddings_db.dart';
+
+/// Adapter that exposes the current sqlite-vec backend via [EmbeddingStore].
+class SqliteEmbeddingStore implements EmbeddingStore {
+  SqliteEmbeddingStore(this._db);
+
+  final EmbeddingsDb _db;
+
+  @override
+  int get count => _db.count;
+
+  @override
+  void close() => _db.close();
+
+  @override
+  void deleteAll() => _db.deleteAll();
+
+  @override
+  void deleteEntityEmbeddings(String entityId) =>
+      _db.deleteEntityEmbeddings(entityId);
+
+  @override
+  String? getContentHash(String entityId) => _db.getContentHash(entityId);
+
+  @override
+  bool hasEmbedding(String entityId) => _db.hasEmbedding(entityId);
+
+  @override
+  void replaceEntityEmbeddings({
+    required String entityId,
+    required String entityType,
+    required String modelId,
+    required String contentHash,
+    required List<Float32List> embeddings,
+    String categoryId = '',
+    String taskId = '',
+    String subtype = '',
+  }) {
+    _db.deleteEntityEmbeddings(entityId);
+    for (var i = 0; i < embeddings.length; i++) {
+      _db.upsertEmbedding(
+        entityId: entityId,
+        chunkIndex: i,
+        entityType: entityType,
+        modelId: modelId,
+        embedding: embeddings[i],
+        contentHash: contentHash,
+        categoryId: categoryId,
+        taskId: taskId,
+        subtype: subtype,
+      );
+    }
+  }
+
+  @override
+  List<EmbeddingSearchResult> search({
+    required Float32List queryVector,
+    int k = 10,
+    String? entityTypeFilter,
+    Set<String>? categoryIds,
+  }) {
+    return _db.search(
+      queryVector: queryVector,
+      k: k,
+      entityTypeFilter: entityTypeFilter,
+      categoryIds: categoryIds,
+    );
+  }
+}

lib/features/ai/database/sqlite_embedding_store.dart

@@ -5,14 +5,14 @@ import 'dart:io';
 import 'dart:typed_data';
 
 import 'package:http/http.dart' as http;
-import 'package:lotti/features/ai/database/embeddings_db.dart';
+import 'package:lotti/features/ai/database/embedding_store.dart';
 import 'package:lotti/features/ai/repository/ollama_inference_repository.dart';
 import 'package:lotti/features/ai/state/consts.dart';
 
 /// Repository for generating text embeddings via Ollama's `/api/embed` endpoint.
 ///
 /// Uses `mxbai-embed-large` (1024 dimensions) by default. The returned
-/// [Float32List] can be stored directly in [EmbeddingsDb].
+/// [Float32List] can be stored directly in an [EmbeddingStore].
 ///
 /// Follows the same HTTP/retry/error patterns as [OllamaInferenceRepository].
 class OllamaEmbeddingRepository {