--- language: - en library_name: pytorch tags: - emoji - text-classification - onnx - safetensors base_model: desert-ant-labs/emo license: other license_name: desert-ant-labs-source-available license_link: https://license.desertant.com/ --- # tinyemo Tinyemo is an English emoji suggestion model distilled from [Emo](https://huggingface.co/desert-ant-labs/emo). It predicts one of 812 emoji labels from a short phrase. It normalizes text to ASCII letters and digits and uses the last four words; it is intended for short input, not general sentiment analysis. The evaluated distribution is `tiny_emo.bin` and `tiny_tokenizer.bin`, together **495,502 bytes**. `model.onnx` and `model.safetensors` contain the same quantized-then-dequantized weights in float32, so they are larger; they are not int4/int8 files. They output logits, not text or emoji. The model uses custom preprocessing and is **not** a Transformers `AutoModel` or `AutoTokenizer`. ## Usage Download the files into a directory named `tinyemo`, then run Python from its parent directory. The reference runtime requires NumPy: ```python from tinyemo.runtime import TinyEmoRuntime model = TinyEmoRuntime("tinyemo/tiny_emo.bin") print(model.suggest("walk the dog", 3)) ``` `suggest` returns `(emoji, probability)` pairs, defaults to one result, clamps the requested count to 1–3, and returns an empty list for input that normalizes to empty. Probabilities are softmax scores, not calibrated confidence estimates. ### ONNX Runtime Install `numpy` and `onnxruntime`. The supplied runtime provides the exact tokenizer, normalization and hashed n-gram preprocessing. `config.json` contains the label order and architecture settings. ```python import numpy as np import onnxruntime as ort from tinyemo.runtime import TinyEmoRuntime pre = TinyEmoRuntime("tinyemo/tiny_emo.bin") session = ort.InferenceSession("tinyemo/model.onnx", providers=["CPUExecutionProvider"]) text = "walk the dog" ids, mask, buckets, signs = pre.encode_batch([text]) count = (signs[:, :, 0] != 0).sum(axis=1).astype(np.float32) logits = session.run(None, { "tok_ids": ids, "tok_mask": mask, "ng_bucket": buckets, "ng_sign": signs.astype(np.float32), "ng_count": count, })[0] print(pre.labels[int(logits[0].argmax())]) ``` The ONNX graph takes a dynamic batch dimension, with token arrays `[batch, 16]`, n-gram arrays `[batch, 96, 2]`, and `ng_count` `[batch]`. `tok_ids` and `ng_bucket` are int64, `tok_mask` is bool, and `ng_sign` and `ng_count` are float32. Preprocessing is outside the graph. ### PyTorch and safetensors Install `torch`, `safetensors`, and `numpy`: ```python import json from safetensors.torch import load_file from tinyemo.model import TinyEmo, TinyEmoConfig with open("tinyemo/config.json", encoding="utf-8") as f: config = json.load(f) model = TinyEmo(TinyEmoConfig(**config["config"])) model.load_state_dict(load_file("tinyemo/model.safetensors")) model.eval() ``` Use the same five preprocessed inputs shown above, converted to PyTorch tensors, to obtain logits. The Python implementation is included in this repository. `export_release.py` rebuilds both formats from the TEM2 file; it requires PyTorch and ONNX. ## Evaluation and limitations The original quantized runtime scored 87.7% top-1 (95% bootstrap interval 84.5–90.9%) and 97.1% top-3 (95.2–98.7%) on 375 hand-labelled phrases with accepted alternatives. Emo scored 88.8% and 97.1%, respectively. The paired top-1 difference was −1.1 percentage points (95% interval −4.3 to +2.1); this interval does not establish equivalence. Model selection used held-out training-pool agreement, while gold was logged during training. On 6,000 held-out snippets from GoEmotions, DailyDialog and tweet_eval, top-1 agreement with the teacher was 62.2%; that measures agreement, not accuracy. Rare nouns such as “koala” remain a weakness. The gold set is small and author-labelled; these results may not generalize to other inputs. Earlier v1 results used a different test set. Training data included short snippets from GoEmotions, DailyDialog, tweet_eval, SST-2, emotion, Tatoeba and Unicode CLDR, plus contexts built from the teacher's vocabulary. The gold phrases were excluded from the training pool, although constituent words could appear elsewhere. The model was trained on teacher predictions; no LLM was used for teacher labelling. ## License and attribution Tinyemo was distilled from Emo, which is distributed under the [Desert Ant Labs Source-Available License](https://license.desertant.com/). Review those terms and the licenses of the source datasets before distribution or commercial use. The `other` metadata records the teacher's license and does not assert additional rights for this derivative. See `THIRD_PARTY_NOTICES.md` for upstream notices. Training data is not included in this release folder.