Add Flutter/Dart example (production-verified) + pure-Dart BPE tokenizer

flutter/small100_translator.dart is the actual translator class from a shipped Android/iOS S2S translator app (encoder+merged-decoder KV-cache greedy decode, verified on real devices). flutter/bpe_tokenizer.dart is a small pure-Dart SentencePiece-BPE tokenizer reading tokenizer.json directly, since Dart has no off-the-shelf HuggingFace-tokenizers binding. examples/README.md table updated to list Flutter as runnable/verified alongside Python and transformers.js.

examples/README.md

@@ -8,14 +8,22 @@ cache), decode. 所有示例都遵循同一套 [`../USAGE.md`](../USAGE.md) 流
 |---|---|---|---|
 | **Python** | optimum / onnxruntime + `tokenizers` | [`python/translate.py`](python/translate.py) | ✅ runnable |
 | **transformers.js** | `@huggingface/transformers` v3 | [`transformers-js/translate.mjs`](transformers-js/translate.mjs) | ✅ runnable (Node) |
+| **Flutter** | `onnxruntime` (Dart) + bundled pure-Dart BPE tokenizer | [`flutter/small100_translator.dart`](flutter/small100_translator.dart) | ✅ runnable, shipped in production |
 | **Android** | onnxruntime-android + DJL `tokenizers` | [`android/Small100Translator.kt`](android/Small100Translator.kt) | 📝 reference |
 | **iOS** | onnxruntime-swift + swift-transformers | [`ios/Small100Translator.swift`](ios/Small100Translator.swift) | 📝 reference |
 
-Python and transformers.js are fully runnable and verified. The Android/iOS files
-are **reference implementations** of the same algorithm (the encoder/greedy-decode
-loop with KV cache is written out); wire them to your asset loading and pin the
-dependency versions in the file headers. Android/iOS 为参考实现，算法完整，接入时
-按文件头的依赖版本对齐即可。
+Python, transformers.js, and Flutter are fully runnable and verified — the
+Flutter one is the actual translator class from a shipped Android/iOS S2S
+translator app (real devices, not a simulator). It also ships
+[`flutter/bpe_tokenizer.dart`](flutter/bpe_tokenizer.dart): a small pure-Dart
+SentencePiece-BPE tokenizer reading this repo's `tokenizer.json` directly,
+since Dart has no off-the-shelf HuggingFace-tokenizers binding the way
+DJL (Android) or swift-transformers (iOS) provide.
+
+The Android/iOS files are **reference implementations** of the same algorithm
+(the encoder/greedy-decode loop with KV cache is written out); wire them to
+your asset loading and pin the dependency versions in the file headers.
+Android/iOS 为参考实现，算法完整，接入时按文件头的依赖版本对齐即可。
 
 The tokenizer (`tokenizer.json`) and the language-token map (`lang_tokens.json`)
 are identical across all platforms — that is the point of this repo.

examples/flutter/bpe_tokenizer.dart

@@ -0,0 +1,133 @@
+// SentencePiece-BPE tokenizer for SMaLL-100 (M2M-100 vocab), reading this
+// repo's tokenizer.json directly (vocab + merges) — no native/FFI tokenizer
+// binding needed, pure Dart. Verified against the Python `tokenizers` output.
+//
+// pubspec.yaml: no extra dependency (dart:convert + dart:io only).
+import 'dart:convert';
+import 'dart:io';
+
+/// [encode] returns the subword ids only — the caller prepends the target
+/// language token and appends `</s>` (id 2, per lang_tokens.json). [decode]
+/// joins content tokens back to text, skipping special tokens and turning the
+/// metaspace marker `▁` into spaces.
+class BpeTokenizer {
+  static const String _metaspace = '▁';
+
+  final Map<String, int> _vocab;
+  final List<String> _idToToken;
+  final Map<String, int> _mergeRank; // "a b" -> rank (lower = higher priority)
+  final Set<int> _specialIds;
+  final int _unkId;
+
+  BpeTokenizer._(this._vocab, this._idToToken, this._mergeRank, this._specialIds, this._unkId);
+
+  // Fullwidth (U+FFxx) forms the SentencePiece nmt_nfkc normalizer folds to
+  // ASCII (NFKC). CJK punctuation like `。`(U+3002) / `、`(U+3001) is NOT
+  // folded — leave it as-is.
+  static const Map<String, String> _punct = {
+    '，': ',', '？': '?', '！': '!', '：': ':', '；': ';',
+    '（': '(', '）': ')', '％': '%', '　': ' ',
+  };
+
+  static Future<BpeTokenizer> fromFile(String tokenizerJsonPath) async {
+    final json = jsonDecode(await File(tokenizerJsonPath).readAsString()) as Map<String, dynamic>;
+    final model = json['model'] as Map<String, dynamic>;
+
+    final rawVocab = (model['vocab'] as Map).cast<String, dynamic>();
+    final vocab = <String, int>{};
+    var maxId = 0;
+    rawVocab.forEach((k, v) {
+      final id = (v as num).toInt();
+      vocab[k] = id;
+      if (id > maxId) maxId = id;
+    });
+    final idToToken = List<String>.filled(maxId + 1, '');
+    vocab.forEach((k, v) {
+      if (v >= 0 && v <= maxId) idToToken[v] = k;
+    });
+
+    final merges = model['merges'] as List<dynamic>;
+    final mergeRank = <String, int>{};
+    for (var i = 0; i < merges.length; i++) {
+      final m = merges[i];
+      final String key;
+      if (m is String) {
+        key = m; // "a b"
+      } else {
+        final pair = (m as List).cast<String>();
+        key = '${pair[0]} ${pair[1]}';
+      }
+      mergeRank[key] = i;
+    }
+
+    // Special ids (</s>, <pad>, <unk>, <s>, and the 100 __xx__ language tokens).
+    final specialIds = <int>{};
+    for (final t in (json['added_tokens'] as List<dynamic>? ?? const [])) {
+      final m = t as Map<String, dynamic>;
+      if (m['special'] == true) specialIds.add((m['id'] as num).toInt());
+    }
+    final unkId = vocab['<unk>'] ?? 3;
+
+    return BpeTokenizer._(vocab, idToToken, mergeRank, specialIds, unkId);
+  }
+
+  String _normalize(String text) {
+    final sb = StringBuffer();
+    for (final r in text.runes) {
+      final ch = String.fromCharCode(r);
+      sb.write(_punct[ch] ?? ch);
+    }
+    return sb.toString();
+  }
+
+  // Greedy BPE: repeatedly merge the adjacent pair with the lowest merge rank.
+  List<String> _bpe(String word) {
+    final symbols = word.runes.map(String.fromCharCode).toList();
+    if (symbols.length < 2) return symbols;
+    while (true) {
+      var bestRank = 1 << 30;
+      var bestI = -1;
+      for (var i = 0; i < symbols.length - 1; i++) {
+        final r = _mergeRank['${symbols[i]} ${symbols[i + 1]}'];
+        if (r != null && r < bestRank) {
+          bestRank = r;
+          bestI = i;
+        }
+      }
+      if (bestI < 0) break;
+      symbols[bestI] = symbols[bestI] + symbols[bestI + 1];
+      symbols.removeAt(bestI + 1);
+    }
+    return symbols;
+  }
+
+  /// Text -> subword ids (no language token, no `</s>`).
+  List<int> encode(String text) {
+    final ids = <int>[];
+    var prevUnk = false;
+    for (final piece in _normalize(text).split(RegExp(r'\s+'))) {
+      if (piece.isEmpty) continue;
+      for (final sym in _bpe(_metaspace + piece)) {
+        final id = _vocab[sym];
+        if (id == null) {
+          if (!prevUnk) ids.add(_unkId); // fuse_unk
+          prevUnk = true;
+        } else {
+          ids.add(id);
+          prevUnk = false;
+        }
+      }
+    }
+    return ids;
+  }
+
+  /// Content ids -> text (skips special tokens, `▁` -> space).
+  String decode(List<int> ids) {
+    final sb = StringBuffer();
+    for (final id in ids) {
+      if (_specialIds.contains(id)) continue;
+      if (id >= 0 && id < _idToToken.length) sb.write(_idToToken[id]);
+    }
+    return sb.toString().replaceAll(_metaspace, ' ').trim();
+  }
+}

examples/flutter/small100_translator.dart

@@ -0,0 +1,241 @@
+// Reference SMaLL-100 translator for Flutter (onnxruntime Dart package).
+// This is the actual implementation shipped in a production S2S translator
+// app (Android + iOS) — fully runnable and verified, not pseudo-code.
+//
+// pubspec.yaml:
+//   dependencies:
+//     onnxruntime: ^1.4.1
+//
+// Ship onnx/encoder_model.onnx, onnx/decoder_model_merged.onnx, tokenizer.json,
+// lang_tokens.json as assets (or download them into app storage — sherpa/
+// onnxruntime need real filesystem paths, not asset-bundle URIs). Implements
+// the algorithm in ../USAGE.md: encode + prepend target-lang token -> encoder
+// -> greedy merged-decoder loop with KV cache -> decode. Needs bpe_tokenizer.dart
+// (same directory) to read tokenizer.json — Dart has no off-the-shelf
+// HuggingFace-tokenizers binding, so this repo ships a small pure-Dart one.
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:onnxruntime/onnxruntime.dart';
+
+import 'bpe_tokenizer.dart';
+
+class Small100Translator {
+  static const int _nLayers = 3;
+  static const int _nHeads = 16;
+  static const int _headDim = 64;
+  static const int _decoderStart = 2;
+  static const int _eos = 2;
+  static const int _pad = 1;
+  static const int _maxLen = 64;
+
+  final BpeTokenizer _tok;
+  final Map<String, int> _langToId;
+  final OrtSession _encoder;
+  final OrtSession _decoder;
+
+  Small100Translator._(this._tok, this._langToId, this._encoder, this._decoder);
+
+  static Future<Small100Translator> create({
+    required String tokenizerJsonPath,
+    required String langTokensPath,
+    required String encoderPath,
+    required String decoderPath,
+  }) async {
+    OrtEnv.instance.init();
+    final tok = await BpeTokenizer.fromFile(tokenizerJsonPath);
+    final lt = jsonDecode(await File(langTokensPath).readAsString()) as Map<String, dynamic>;
+    final langToId = (lt['lang_to_id'] as Map).map((k, v) => MapEntry(k as String, (v as num).toInt()));
+    final opts = OrtSessionOptions()..setIntraOpNumThreads(2);
+    // On-device acceleration: unsupported ops silently fall back to CPU.
+    // Some emulators (e.g. those that run on qemu but report a real device's
+    // Build.FINGERPRINT) crash inside libonnxruntime.so with NNAPI enabled —
+    // real devices are unaffected. If you hit that, detect the emulator and
+    // skip appendNnapiProvider rather than disabling acceleration everywhere.
+    if (Platform.isAndroid) {
+      opts.appendNnapiProvider(NnapiFlags.useNone);
+    } else if (Platform.isIOS) {
+      opts.appendCoreMLProvider(CoreMLFlags.useNone);
+    }
+    final encoder = OrtSession.fromFile(File(encoderPath), opts);
+    final decoder = OrtSession.fromFile(File(decoderPath), opts);
+    return Small100Translator._(tok, langToId, encoder, decoder);
+  }
+
+  bool supportsLang(String code) => _langToId.containsKey(code);
+
+  /// Translate [text] into [tgtLang] (e.g. 'en'). Returns '' for empty input or
+  /// an unknown target language.
+  Future<String> translate(String text, String tgtLang) async {
+    if (text.trim().isEmpty) return '';
+    final langId = _langToId[tgtLang];
+    if (langId == null) return '';
+
+    final runOpts = OrtRunOptions();
+    // [tgt lang] + subwords + </s>  — SMaLL-100 puts the target-language token
+    // on the *source* side, not via forced_bos_token_id.
+    final ids = <int>[langId, ..._tok.encode(text), _eos];
+    final seqLen = ids.length;
+
+    final inputIds = OrtValueTensor.createTensorWithDataList(Int64List.fromList(ids), [1, seqLen]);
+    final attnMask = OrtValueTensor.createTensorWithDataList(
+        Int64List.fromList(List<int>.filled(seqLen, 1)), [1, seqLen]);
+
+    final encOut = _encoder.run(runOpts, {'input_ids': inputIds, 'attention_mask': attnMask});
+    final encoderHidden = encOut[0]!; // frozen across steps
+
+    final past = <String, OrtValue>{};
+    for (var i = 0; i < _nLayers; i++) {
+      for (final kind in ['decoder', 'encoder']) {
+        for (final kv in ['key', 'value']) {
+          past['past_key_values.$i.$kind.$kv'] =
+              OrtValueTensor.createTensorWithDataList(Float32List(0), [1, _nHeads, 0, _headDim]);
+        }
+      }
+    }
+
+    final outIds = <int>[];
+    var cur = _decoderStart;
+    var useCache = false;
+
+    try {
+      for (var step = 0; step < _maxLen; step++) {
+        final stepInputIds = OrtValueTensor.createTensorWithDataList(Int64List.fromList([cur]), [1, 1]);
+        final useCacheT = OrtValueTensor.createTensorWithDataList([useCache], [1]);
+
+        final feeds = <String, OrtValue>{
+          'encoder_attention_mask': attnMask,
+          'input_ids': stepInputIds,
+          'encoder_hidden_states': encoderHidden,
+          'use_cache_branch': useCacheT,
+          ...past,
+        };
+
+        final outputs = _decoder.run(runOpts, feeds);
+        final outByName = <String, OrtValue?>{};
+        for (var i = 0; i < _decoder.outputNames.length; i++) {
+          outByName[_decoder.outputNames[i]] = outputs[i];
+        }
+
+        final next = _argmaxLastLogits(outByName['logits']!);
+        stepInputIds.release();
+        useCacheT.release();
+        if (next == _eos) {
+          _releaseOutputs(outputs, keep: {});
+          break;
+        }
+        outIds.add(next);
+        // Greedy decode can degenerate into a repeated token/short cycle on
+        // out-of-distribution input; bail out instead of running to _maxLen.
+        if (_degenerate(outIds)) {
+          _releaseOutputs(outputs, keep: {});
+          break;
+        }
+
+        final keep = <OrtValue>{};
+        for (var i = 0; i < _nLayers; i++) {
+          for (final kv in ['key', 'value']) {
+            final decKey = 'past_key_values.$i.decoder.$kv';
+            final newDec = outByName['present.$i.decoder.$kv']!;
+            past[decKey]!.release();
+            past[decKey] = newDec;
+            keep.add(newDec);
+            if (!useCache) {
+              // Encoder KV is only produced on step 1 (use_cache_branch=false),
+              // then frozen and reused for every later step.
+              final encKey = 'past_key_values.$i.encoder.$kv';
+              final newEnc = outByName['present.$i.encoder.$kv']!;
+              past[encKey]!.release();
+              past[encKey] = newEnc;
+              keep.add(newEnc);
+            }
+          }
+        }
+        _releaseOutputs(outputs, keep: keep);
+
+        cur = next;
+        useCache = true;
+      }
+    } finally {
+      for (final t in past.values) {
+        t.release();
+      }
+      encoderHidden.release();
+      inputIds.release();
+      attnMask.release();
+      runOpts.release();
+    }
+
+    return _tok.decode(outIds);
+  }
+
+  int _argmaxLastLogits(OrtValue logits) {
+    final v = logits.value as List;
+    final row = (v[0] as List).last as List; // [1, seq, vocab] -> last position
+    var bestIdx = 0;
+    var bestVal = double.negativeInfinity;
+    for (var i = 0; i < row.length; i++) {
+      if (i == _pad) continue; // never emit <pad>
+      final x = (row[i] as num).toDouble();
+      if (x > bestVal) {
+        bestVal = x;
+        bestIdx = i;
+      }
+    }
+    return bestIdx;
+  }
+
+  // Bail out of greedy decoding if it degenerates into a repeated token or a
+  // short repeating cycle (period 2-4) — cheap safety net beyond ../USAGE.md's
+  // base algorithm, worth adopting on any platform.
+  static bool _degenerate(List<int> ids) {
+    final n = ids.length;
+    if (n >= 6) {
+      var same = true;
+      for (var i = n - 6; i < n - 1; i++) {
+        if (ids[i] != ids[i + 1]) {
+          same = false;
+          break;
+        }
+      }
+      if (same) return true;
+    }
+    for (var p = 2; p <= 4; p++) {
+      if (n >= p * 3) {
+        var cyc = true;
+        for (var i = 0; i < p * 2; i++) {
+          if (ids[n - 1 - i] != ids[n - 1 - i - p]) {
+            cyc = false;
+            break;
+          }
+        }
+        if (cyc) return true;
+      }
+    }
+    return false;
+  }
+
+  void _releaseOutputs(List<OrtValue?> outputs, {required Set<OrtValue> keep}) {
+    for (final o in outputs) {
+      if (o != null && !keep.contains(o)) o.release();
+    }
+  }
+
+  void dispose() {
+    _encoder.release();
+    _decoder.release();
+  }
+}
+
+// Usage (e.g. from a Flutter widget's initState, after copying the asset
+// files to real paths — see ModelManager-style staging in the app examples):
+//
+//   final t = await Small100Translator.create(
+//     tokenizerJsonPath: '$modelsRoot/tokenizer.json',
+//     langTokensPath: '$modelsRoot/lang_tokens.json',
+//     encoderPath: '$modelsRoot/onnx/encoder_model.onnx',
+//     decoderPath: '$modelsRoot/onnx/decoder_model_merged.onnx',
+//   );
+//   print(await t.translate('你好，请问最近的地铁站怎么走？', 'en'));
+//   t.dispose();