Upload folder using huggingface_hub

README.md

@@ -1,3 +1,104 @@
 ---
 license: mit
+base_model: Cactus-Compute/needle
+library_name: jax
+pipeline_tag: text-generation
+tags:
+- function-calling
+- tool-use
+- termux
+- android
+- on-device
+- candle
+- rust
+- needle
+language:
+- en
+- ar
 ---
+
+# needle-termux-sting 🪡
+
+[Needle](https://huggingface.co/Cactus-Compute/needle) (26M-parameter
+"Simple Attention Network" for single-shot function calling, by
+cactus-compute) **finetuned on the Termux:API command set** — the model behind
+[sting](https://github.com/abod707/sting), a pure-Rust CLI that gives Termux
+natural-language device control, fully offline.
+
+```
+"vibrate for 2 seconds"
+  → [{"name":"termux_vibrate","arguments":{"duration_ms":2000}}]
+```
+
+## What's different from base needle
+
+1. **Finetuned decoder** — 4,810 synthetic examples over 16 Termux:API tools +
+   14 generic tools (single-call, multi-call, missing-argument, and no-tool
+   cases; EN + some Arabic values). Recipe and data generator:
+   [sting/finetune](https://github.com/abod707/sting/tree/main/finetune).
+2. **Working retrieval head** — the released base checkpoint ships its
+   contrastive (retrieval) head as **all zeros**, and zero weights + ReLU is a
+   gradient fixed point, so ordinary finetuning can never revive it. This
+   checkpoint's head was re-initialized and then trained on frozen encoder
+   features (softmax-over-tools). Retrieval over the 16-tool Termux pack:
+   **hit@3 = 99.2%, hit@6 = 100%** (400 queries).
+
+## Eval (held-out test set, 300 examples, 30 tools)
+
+| metric | base needle | this model |
+|---|---|---|
+| call_f1 (name+args exact) | 75.0% | **99.7%** |
+| name_f1 | 94.6% | **100.0%** |
+| exact_match | 72.7% | **99.7%** |
+| args_acc | 79.2% | **99.7%** |
+| parse_rate | 99.3% | **100.0%** |
+
+Held-out but same-distribution synthetic data — treat as an upper bound for
+wild phrasing. Methodology + per-tool tables:
+[sting/EVAL.md](https://github.com/abod707/sting/blob/main/EVAL.md).
+
+## Files
+
+| file | format | use with |
+|---|---|---|
+| `needle_sting_final.pkl` | needle checkpoint (JAX/Flax, f16) | the official [needle](https://github.com/cactus-compute/needle) pipeline: `needle run --checkpoint needle_sting_final.pkl --query "..." --tools '[...]'` |
+| `model.safetensors` + `config.json` + `tokenizer_spec.json` | f16 safetensors + JSON specs | [sting](https://github.com/abod707/sting)'s pure-Rust candle runtime |
+
+## Usage (Python / needle)
+
+```python
+from needle import SimpleAttentionNetwork, load_checkpoint, generate, get_tokenizer
+
+params, config = load_checkpoint("needle_sting_final.pkl")
+model = SimpleAttentionNetwork(config)
+result = generate(
+    model, params, get_tokenizer(),
+    query="read the gyroscope, 5 readings",
+    tools='[{"name":"termux_sensor","description":"Read values from a hardware sensor on the device.","parameters":{"sensor":{"type":"string","description":"Sensor name: accelerometer, gyroscope, light, proximity, pressure, magnetic_field or gravity.","required":true},"limit":{"type":"integer","description":"Number of readings to take.","required":false}}}]',
+    stream=False,
+)
+# [{"name":"termux_sensor","arguments":{"sensor":"gyroscope","limit":5}}]
+```
+
+## Usage (Termux / sting)
+
+```bash
+pkg install rust git binutils termux-api
+git clone https://github.com/abod707/sting
+cd sting && ./scripts/termux-install.sh
+sting "turn on the flashlight"
+```
+
+## Scope & limitations
+
+Single-shot function calling over a provided toolset. Not conversational, no
+multi-step planning; underspecified requests ("set an alarm" with no time)
+correctly return `[]`. Custom tools work zero-shot via the generic schemas it
+saw in training; for production use of your own tools, finetune with ~120
+examples per tool (recipe in the sting repo).
+
+## Credits
+
+Base model, architecture, and training pipeline:
+[cactus-compute/needle](https://github.com/cactus-compute/needle) (MIT).
+Finetune, retrieval-head fix, and Rust runtime: [abod707](https://github.com/abod707) (MIT).

config.json

@@ -0,0 +1,15 @@
+{
+  "vocab_size": 8192,
+  "d_model": 512,
+  "num_heads": 8,
+  "num_kv_heads": 4,
+  "num_encoder_layers": 12,
+  "num_decoder_layers": 8,
+  "rope_theta": 10000.0,
+  "max_seq_len": 1024,
+  "pad_token_id": 0,
+  "eos_token_id": 1,
+  "bos_token_id": 2,
+  "tool_call_token_id": 4,
+  "tools_token_id": 5
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36443d27a663f2839e6f53c9b19bfa0b06c2e158d1c30819a4f6b6b87f887f24
+size 52655224

needle_sting_final.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c78e0077d72351d8aedaabe1abd75759d7f3f04818664f2dcac6c14cad1e368a
+size 52633104