flutter_gemma_embeddings library

Runtime-agnostic on-device text embedding pipeline for flutter_gemma.

This package no longer ships a concrete embedding backend — it owns tokenization, task-type prefixing, the background-isolate worker, and pooling/normalization, over the EmbeddingForwardPass seam that engine packages implement.

To actually run embeddings, add an engine package that provides an EmbeddingBackendProvider — e.g. flutter_gemma_litertlm's LiteRtEmbeddingBackend — and register it:

import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:flutter_gemma_litertlm/flutter_gemma_litertlm.dart';

await FlutterGemma.initialize(
  embeddingBackends: [LiteRtEmbeddingBackend()],
);

See the embedder decoupling design (docs/superpowers/specs/ 2026-08-17-flutter-gemma-onnx-engine-design.md §2, §11 D3/D4) for why the seam exists: it lets flutter_gemma_litertlm and (later) flutter_gemma_onnx share one tokenizer/worker/pooling implementation instead of each reimplementing the isolate facade.

Classes

CommonEmbeddingModel

EmbeddingForwardPass

One engine's forward-pass implementation.

EmbeddingTokenizer

Turns raw text (with a TaskType prefix already applied) into a TokenizedInput. One instance per loaded tokenizer file; built once by the worker at startup and reused for every encode call.

ForwardPassDescriptor

Sendable description of "which engine, which model" that crosses an isolate boundary so the receiving isolate can build its own EmbeddingForwardPass locally. FFI handles/pointers themselves can never cross isolates — only this descriptor (plain data + a code reference) does; see EmbeddingForwardPassFactory for why factory must be a top-level/static tear-off.

ForwardResult

Raw forward-pass output: a flat, row-major buffer plus its tensor shape.

TokenizedInput

One text's tokenized form, ready for EmbeddingForwardPass.run.

Enums

EmbeddingOutputContract

How to turn a ForwardResult into the final embedding vector.

Functions

meanPoolAndNormalize(ForwardResult result, {List<int>? attentionMask}) → List<double>

Mean-pools a token-level ForwardResult over the sequence axis and L2-normalizes it into a single embedding vector of length dim.

Typedefs

EmbeddingForwardPassFactory = EmbeddingForwardPass Function(String modelPath)

Factory that builds an EmbeddingForwardPass for a given on-disk model path.

EmbeddingTokenizerFactory = Future<EmbeddingTokenizer> Function(String tokenizerPath)

Factory that builds an EmbeddingTokenizer for a given on-disk tokenizer path.

VoidCallback = void Function()