MobileRag class
Singleton facade for Mobile RAG Engine.
Use MobileRag.initialize to set up the engine, then access it via MobileRag.instance anywhere in your app.
Properties
- currentEmbeddingFingerprint → String
-
Fingerprint computed from the currently loaded embedding model
(
{modelBasename}|{dim}|{quant}). Stable across reboots as long as the host app keeps loading the same model file.no setter - dbPath → String
-
Path to the SQLite database.
no setter
- embeddingFingerprintLock → RagEmbeddingFingerprintLock?
-
Non-null when boot detected an embedding fingerprint mismatch — i.e.
the stored on-device embeddings were produced by a different model than
the one currently loaded. While set, all search and ingest entry points
throw
RagError.embeddingFingerprintMismatch. Resolve by calling either reembedAll (preserves data) or clearAndRestart (discards embeddings after explicit confirmation).no setter - engine → RagEngine
-
Access the underlying RagEngine for advanced operations.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- isEmbeddingFingerprintLocked → bool
-
Whether boot detected an embedding fingerprint mismatch.
no setter
- isIndexReady → bool
-
Whether all retrieval indexes are ready for full-quality search.
no setter
-
migrationState
→ Future<
MigrationAxes> -
Read-only snapshot of every on-device data migration axis
(
sql_schema_version,hnsw_format_version,bm25_stats_version,embedding_fingerprint,embedding_fingerprint_pending) plus the last engine version recorded at boot. Backed by themigration_metarow provisioned duringinitialize().no setter - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- vocabSize → int
-
Vocabulary size of the loaded tokenizer.
no setter
-
warmupFuture
→ Future<
void> -
Completes when BM25/HNSW warmup has finished.
no setter
Methods
-
addDocument(
String content, {String? metadata, String? name, String? filePath, ChunkingStrategy? strategy, Duration? chunkDelay, void onProgress(int done, int total)?}) → Future< SourceAddResult> - Add a document with automatic chunking and embedding.
-
addDocumentFromFile(
String filePath, {String? metadata, String? name, ChunkingStrategy? strategy, Duration? chunkDelay, void onProgress(int done, int total)?}) → Future< SourceAddResult> -
addDocumentUtf8(
Uint8List bytes, {String? metadata, String? name, ChunkingStrategy? strategy, Duration? chunkDelay, void onProgress(int done, int total)?}) → Future< SourceAddResult> -
assembleContext(
{required SearchHandle searchHandle, int tokenBudget = 2000, ContextStrategy strategy = ContextStrategy.relevanceFirst, String separator = '\n\n---\n\n', bool singleSourceMode = false}) → Future< AssembledContextV2> -
clearAllData(
) → Future< void> - Clear all data (database and index files) and reset the engine.
-
clearAndRestart(
{required ClearAndRestartConfirmation confirm}) → Future< void> - Discard every on-device embedding (chunks table) and rotate the fingerprint baseline to the currently loaded model.
-
deriveContextBudgetForPromptV2(
{required int fullPromptBudget, required String query, String? systemInstruction, bool useStrictMode = true, int safetyMarginTokens = 0, int? fixedPromptOverheadTokens}) → Future< int> -
formatPrompt(
String query, RagSearchResult result) → String - Format search results as an LLM prompt.
-
getAdjacentChunks(
{required int sourceId, required int minIndex, required int maxIndex}) → Future< List< ChunkSearchResult> > - Get adjacent chunks around a given chunk range.
-
getChunkExcerpts(
{required SearchHandle searchHandle, required List< int> chunkIds, required int maxBytes}) → Future<List< ChunkExcerptResult> > -
getSourceChunkCount(
int sourceId) → Future< int> - Get the number of chunks for a specific source.
-
getSourceChunks(
int sourceId) → Future< List< String> > - Get all chunk texts for a specific source document.
-
getSourceDocument(
int sourceId) → Future< String?> - Get the original source document content.
-
getStats(
) → Future< SourceStats> - Get statistics about stored sources and chunks.
-
hydrateChunks(
{required SearchHandle searchHandle, required List< int> chunkIds}) → Future<List< ChunkSearchResult> > -
inCollection(
String collectionId) → CollectionRag - Get a collection-scoped facade.
-
listSources(
) → Future< List< SourceEntry> > - Get a list of all stored sources.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
rebuildIndex(
) → Future< void> - Rebuild the HNSW index.
-
reembedAll(
{void onProgress(RagReembedProgress progress)?, int batchSize = 32}) → Future< void> - Re-embed every stored chunk with the currently loaded model and clear the embeddingFingerprintLock. Resumable across app restarts — progress is persisted per chunk on the Rust side, so an interrupted run picks up where it left off on the next call.
-
reembedRemaining(
) → Future< int> - Up-to-date count of chunks still tagged with a non-current fingerprint. Safe to call while reembedAll is running.
-
removeSource(
int sourceId) → Future< void> - Remove a source and all its chunks.
-
saveIndex(
) → Future< void> - Save the HNSW index marker to disk.
-
search(
String query, {int topK = 10, int tokenBudget = 2000, ContextStrategy strategy = ContextStrategy.relevanceFirst, int adjacentChunks = 0, bool singleSourceMode = false, List< int> ? sourceIds}) → Future<RagSearchResult> - Search for relevant chunks and assemble context for LLM.
-
searchHybrid(
String query, {int topK = 10, double vectorWeight = kDefaultVectorWeight, double bm25Weight = kDefaultBm25Weight, List< int> ? sourceIds}) → Future<List< HybridSearchResult> > - Hybrid search combining vector and keyword (BM25) search.
-
searchHybridWithContext(
String query, {int topK = 10, int tokenBudget = 2000, ContextStrategy strategy = ContextStrategy.relevanceFirst, int adjacentChunks = 0, double vectorWeight = kDefaultVectorWeight, double bm25Weight = kDefaultBm25Weight, bool singleSourceMode = false, List< int> ? sourceIds, SearchHydrationMode hydrationMode = SearchHydrationMode.full, int previewMaxBytes = 512}) → Future<RagSearchResult> - Hybrid search with context assembly for LLM.
-
searchMeta(
String query, {int topK = 10, double vectorWeight = kDefaultVectorWeight, double bm25Weight = kDefaultBm25Weight, List< int> ? sourceIds, int adjacentChunks = 0}) → Future<SearchMetaResult> -
toString(
) → String -
A string representation of this object.
inherited
-
tryLoadCachedIndex(
) → Future< bool> - Try to load a cached HNSW index.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- instance → MobileRag
-
Get the singleton instance.
no setter
- isInitialized → bool
-
Check if the engine is initialized.
no setter
Static Methods
-
dispose(
) → Future< void> - Dispose of resources.
-
initialize(
{required String tokenizerAsset, required String modelAsset, String? databaseName, int maxChunkChars = kDefaultMaxChunkChars, int overlapChars = kDefaultOverlapChars, int? embeddingIntraOpNumThreads, ThreadUseLevel? threadLevel, bool deferIndexWarmup = false, void onProgress(String status)?}) → Future< void> - Initialize the RAG engine. Call once in main().
-
setMockInstance(
MobileRag? mock) → void - (FOR TESTING ONLY) Inject a custom instance for mocking.