fasttext_flutter 0.1.2

On-device text classification and sentence embeddings using fastText .ftz quantized models via Dart FFI. Verified on Android. Contributions welcome

fasttext_flutter

On-device text classification and sentence embeddings using fastText .ftz quantized models via Dart FFI — no internet, no server required.

---

⚠️ Platform Status

Only Android has been tested so far. The build infrastructure (native_toolchain_c hooks) is in place for other platforms but has not been verified. If you test on iOS, macOS, Linux, or Windows, please open a PR or report your results in the issue tracker.

👋 Contributors welcome! See Contributing below.

---

Platform support

Platform	Status
Android (arm64-v8a, armeabi-v7a, x86_64)	✅ Verified
iOS	🔲 Untested — help wanted
macOS	🔲 Untested — help wanted
Linux	🔲 Untested — help wanted
Windows	🔲 Untested — help wanted

---

Features

• Load .ftz (quantized) and .bin (full) fastText models
• predict() — top-k text classification for supervised models
• computeEmbedding() — dense sentence-vector embeddings (Float32List)
• FastTextModel.cosineSimilarity() — static cosine-similarity helper
• FastTextModelType — detect supervised, cbow, or skipgram at runtime
• Background-isolate inference — never blocks the UI thread
• Automatic memory cleanup via NativeFinalizer + explicit close()

---

Getting started

1. Add the dependency

dependencies:
  fasttext_flutter: ^0.1.1

2. Add your model as an asset

flutter:
  assets:
    - assets/model.ftz

Download a pre-trained language-ID model (917 KB, 177 languages): https://fasttext.cc/docs/en/language-identification.html

---

Usage

Load a model

import 'package:fasttext_flutter/fasttext_flutter.dart';

// From Flutter assets
final model = await FastTextModel.loadAsset('assets/lid.176.ftz');

// From an absolute file path
final model = await FastTextModel.load('/sdcard/downloads/model.ftz');

Classify text (supervised models only)

final results = await model.predict('Bonjour le monde', k: 3);
print(results.first.cleanLabel);    // fr
print(results.first.probability);   // 0.9994...

Compute sentence embeddings (all model types)

final vector = await model.computeEmbedding('Flutter developer');
// → Float32List of length model.dimension

Cosine similarity

final a = await model.computeEmbedding('Flutter developer');
final b = await model.computeEmbedding('Mobile app developer');
final sim = FastTextModel.cosineSimilarity(a, b);
print(sim.toStringAsFixed(4)); // e.g. 0.9797

Check model type

print(model.modelType);    // FastTextModelType.supervised / .cbow / .skipgram
print(model.isSupervised); // true for classification models
print(model.dimension);    // embedding dimension
print(model.labelCount);   // 0 for unsupervised models

Close the model

model.close(); // frees native memory; safe to call multiple times

---

FastTextPrediction

final r = results.first;
r.label       // raw label e.g. '__label__en'
r.cleanLabel  // stripped label e.g. 'en'
r.probability // double in [0.0, 1.0]

---

Error handling

try {
  final model = await FastTextModel.load('/bad/path.ftz');
} on FastTextException catch (e) {
  print(e.message);
}

Calling predict() on an unsupervised model throws FastTextException with a clear message directing you to computeEmbedding() instead.

---

Performance notes

• .ftz quantized models are 10–100× smaller than .bin and nearly as accurate.
• All inference runs in Isolate.run() — the UI thread is never blocked.
• Load the model once and reuse it across requests.

---

Contributing

This package needs your help to support more platforms!

Only Android has been tested so far. If you can verify (or fix) any of these:

• iOS — swipe hook/build.dart flags and test on Simulator + device
• macOS — test with flutter run -d macos from the example/ folder
• Linux — test with flutter run -d linux
• Windows — test with flutter run -d windows

Please open an issue with your results or a PR with fixes at: https://github.com/FahadQasim283/fasttext_flutter

Every contribution — bug reports, test results, docs fixes — is welcome.

---

License

Apache-2.0. See LICENSE.

Bundled fastText C++ sources: © Facebook, Inc., MIT license.