initialize static method

Future<void> initialize({ String? tokenizerAsset, String? modelAsset, RagModelPack? modelPack, String? databaseName, int maxChunkChars = kDefaultMaxChunkChars, int overlapChars = kDefaultOverlapChars, int? embeddingIntraOpNumThreads, ThreadUseLevel? threadLevel, VabqProfile vabqProfile = VabqProfile.none, bool deferIndexWarmup = false, void onProgress(String status)?, })

Initialize the RAG engine. Call once in main().

This will:

1. Initialize the Rust library (FFI)
2. Load the tokenizer from assets
3. Load the ONNX embedding model
4. Initialize the SQLite database

Parameters:

• tokenizerAsset - Path to tokenizer.json in assets (e.g., 'assets/tokenizer.json')
• modelAsset - Path to ONNX model file in assets (e.g., 'assets/model.onnx')
• databaseName - SQLite database file name (default: 'rag.sqlite')
• maxChunkChars - Maximum characters per chunk (default: kDefaultMaxChunkChars)
• overlapChars - Overlap between chunks for context continuity (default: kDefaultOverlapChars)
• embeddingIntraOpNumThreads - Precise thread count for ONNX (e.g., 1 for minimal CPU). Mutually exclusive with threadLevel.
• threadLevel - High-level thread usage: low (~20%), medium (~40%), high (~80%). Mutually exclusive with embeddingIntraOpNumThreads.
• deferIndexWarmup - If true, returns before BM25/HNSW warmup completes. Use isIndexReady or warmupFuture to gate search quality.
• onProgress - Callback for initialization progress updates

Thread Configuration:

Choose ONE of the following:

• threadLevel: ThreadUseLevel.medium - Simple, recommended for most apps
• embeddingIntraOpNumThreads: 2 - Fine-grained control

⚠️ If both are set:

• Debug builds: throws an AssertionError
• Release builds: threadLevel takes precedence and a warning is logged

Example:

await MobileRag.initialize(
  tokenizerAsset: 'assets/tokenizer.json',
  modelAsset: 'assets/model.onnx',
  threadLevel: ThreadUseLevel.medium, // Recommended
  onProgress: (status) => print(status),
);

Implementation

static Future<void> initialize({
  String? tokenizerAsset,
  String? modelAsset,
  RagModelPack? modelPack,
  String? databaseName,
  int maxChunkChars = kDefaultMaxChunkChars,
  int overlapChars = kDefaultOverlapChars,
  int? embeddingIntraOpNumThreads,
  ThreadUseLevel? threadLevel,
  VabqProfile vabqProfile = VabqProfile.none,
  bool deferIndexWarmup = false,
  void Function(String status)? onProgress,
}) async {
  if (_instance != null) {
    onProgress?.call('Already initialized');
    return;
  }

  final hasLegacyAssets = tokenizerAsset != null || modelAsset != null;
  if (modelPack != null && hasLegacyAssets) {
    throw ArgumentError(
      'Specify either modelPack or tokenizerAsset/modelAsset, not both.',
    );
  }
  if (modelPack != null && vabqProfile != VabqProfile.none) {
    throw ArgumentError('Model Pack v1 is fixed to Q8_0 and does not support VABQ profiles.');
  }
  if (modelPack == null && (tokenizerAsset == null || modelAsset == null)) {
    throw ArgumentError(
      'Specify modelPack or both tokenizerAsset and modelAsset.',
    );
  }
  final RagConfig config;
  if (modelPack != null) {
    final resolved = await const RagModelPackResolver().resolve(modelPack);
    config = RagConfig.fromPreparedFiles(
      tokenizerPath: resolved.tokenizerPath,
      modelPath: resolved.modelPath,
      expectedEmbeddingDimension: resolved.manifest.embeddingDimension,
      databaseName: databaseName,
      maxChunkChars: maxChunkChars,
      overlapChars: overlapChars,
      embeddingIntraOpNumThreads: embeddingIntraOpNumThreads,
      threadLevel: threadLevel,
      deferIndexWarmup: deferIndexWarmup,
    );
  } else {
    config = RagConfig.fromAssets(
      tokenizerAsset: tokenizerAsset!,
      modelAsset: modelAsset!,
      databaseName: databaseName,
      maxChunkChars: maxChunkChars,
      overlapChars: overlapChars,
      embeddingIntraOpNumThreads: embeddingIntraOpNumThreads,
      threadLevel: threadLevel,
      vabqProfile: vabqProfile,
      deferIndexWarmup: deferIndexWarmup,
    );
  }
  _engine = await RagEngine.initialize(
    config: config,
    onProgress: onProgress,
  );
  _instance = MobileRag._();
}