Skip to content

Automation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.

Fix naming

HenryNdubuaku6df388435490
diff --git a/README.md b/README.md
index 8e227b1..9bc8bdd 100644
--- a/README.md
+++ b/README.md
@@ -73,12 +73,10 @@ Opens a web UI at http://127.0.0.1:7860 where you can test and finetune on your
## Usage (Python)
```python
-from needle.model.run import load_checkpoint, generate
-from needle.model.architecture import EncoderDecoderTransformer
-from needle.dataset.dataset import get_tokenizer
+from needle import SimpleAttentionNetwork, load_checkpoint, generate, get_tokenizer
params, config = load_checkpoint("checkpoints/needle.pkl")
-model = EncoderDecoderTransformer(config)
+model = SimpleAttentionNetwork(config)
tokenizer = get_tokenizer()
result = generate(
@@ -93,112 +91,33 @@ print(result)
## Finetuning
-Finetune on your own tools via the web UI or CLI:
-
```bash
-# Web UI (generates data via Gemini, trains, evaluates, bundles result)
+# Playground (generates data via Gemini, trains, evaluates, bundles result)
needle playground
# CLI (auto-downloads weights if not local)
needle finetune data.jsonl
```
-
-## Needle CLI
+## CLI
```
- ┌───────────────────────────────────────────────────────────────────┐
- │ │
- │ playground Web UI for inference + finetuning │
- │ --checkpoint PATH Model checkpoint (optional, │
- │ auto-downloads from HuggingFace) │
- │ --port INT Server port (default: 7860) │
- │ --host STR Bind address (default: 127.0.0.1) │
- │ │
- │ run │
- │ --checkpoint PATH Path to model checkpoint (required)│
- │ --query STR Query text for tool-call generation│
- │ --tools STR Tools JSON for tool-call generation│
- │ --max-len INT Max tokens to generate (default:512│
- │ --seed INT Random seed (default: 0) │
- │ --no-constrained Disable constrained decoding │
- │ │
- │ train │
- │ --name STR Experiment name (default: baseline)│
- │ --checkpoint PATH Resume from checkpoint │
- │ --init-from PATH Init params from pretrained base │
- │ --epochs INT Training epochs (default: 1) │
- │ --batch-size INT Batch size (default: 64) │
- │ --lr FLOAT AdamW learning rate (default: 3e-5)│
- │ --muon-lr FLOAT Muon learning rate (default: 0.02) │
- │ --d-model INT Model dim (default: 512) │
- │ --num-heads INT Attention heads (default: 8) │
- │ --num-kv-heads INT KV heads for GQA (default: 4) │
- │ --num-layers INT Encoder layers (default: 12) │
- │ --num-dec-layers INT Decoder layers (default: 8) │
- │ --max-enc-len INT Max encoder seq len (default: 1024)│
- │ --max-dec-len INT Max decoder seq len (default: 512) │
- │ --max-samples INT Training samples (default: all) │
- │ --warmup-ratio FLOAT LR warmup ratio (default: 0.05) │
- │ --decay-ratio FLOAT LR cosine decay ratio (default:0.05│
- │ --eval-every INT Val eval interval (default: 1000) │
- │ --max-eval-samples INT Val samples limit (default: 5000) │
- │ --contrastive-weight FL CLIP loss weight (default: 0.1) │
- │ --contrastive-dim INT Projection dim (default: 128) │
- │ --w-name FLOAT Loss weight: tool names (def: 2.0) │
- │ --w-value FLOAT Loss weight: arg values (def: 4.0) │
- │ --w-key FLOAT Loss weight: arg keys (def: 1.5) │
- │ --wandb Enable W&B logging │
- │ --checkpoint-dir DIR Checkpoint directory │
- │ --dtype STR float32|bfloat16 (default: bfloat16│
- │ --seed INT Random seed (default: 42) │
- │ │
- │ pretrain │
- │ --name STR Experiment name (default: pretrain)│
- │ --checkpoint PATH Resume from checkpoint │
- │ --resume-step INT Override resume step │
- │ --epochs INT Training epochs (default: 1) │
- │ --batch-size INT Batch size (default: 128) │
- │ --lr FLOAT AdamW learning rate (default: 3e-4)│
- │ --muon-lr FLOAT Muon learning rate (default: 0.02) │
- │ --max-steps INT Stop after N steps (default: full) │
- │ --save-every INT Checkpoint interval (default: 1000)│
- │ --wandb Enable W&B logging │
- │ (also accepts --d-model, --num-heads, etc. same as train) │
- │ │
- │ tokenize │
- │ --max-samples INT Limit samples per split (dev/test) │
- │ --max-enc-len INT Max encoder seq len (default: 1024)│
- │ --max-dec-len INT Max decoder seq len (default: 512) │
- │ --shuffle-tools Shuffle tool order (default: on) │
- │ --no-shuffle-tools Disable tool shuffling │
- │ --max-tool-len INT Max tool desc tokens (default: 256)│
- │ │
- │ eval │
- │ --checkpoint PATH Path to model checkpoint (required)│
- │ --batch-size INT Batch size (default: 32) │
- │ --max-eval-samples INT Evaluation samples (default: 5000) │
- │ --max-enc-len INT Max encoder length (default: 1024) │
- │ --max-dec-len INT Max decoder length (default: 512) │
- │ --max-gen-len INT Max generation length (default:512)│
- │ --throughput-runs INT Throughput runs (default: 10) │
- │ --tool-call-samples INT Tool-call eval samples (default:200│
- │ --no-constrained Disable constrained decoding │
- │ │
- │ generate-data │
- │ --num-samples INT Samples to generate (default: 500) │
- │ --batch-size INT Examples per Gemini call (default:25│
- │ --workers INT Parallel Gemini calls (default: 8) │
- │ --model STR Gemini model override │
- │ --dry-run Generate only, skip upload │
- │ --output-jsonl PATH Also save raw generations to JSONL │
- │ --upload-every INT Merge+upload interval │
- │ │
- │ tpu See docs/tpu.md │
- │ │
- └───────────────────────────────────────────────────────────────────┘
+needle playground Test and finetune via web UI
+needle finetune <data.jsonl> Finetune on your own data
+needle run --query "..." --tools Single inference
+needle train Full training run
+needle pretrain Pretrain on PleIAs/SYNTH
+needle eval --checkpoint <path> Evaluate a checkpoint
+needle tokenize Tokenize dataset
+needle generate-data Synthesize training data via Gemini
+needle tpu <action> TPU management (see docs/tpu.md)
```
-## TPU
-
-This repo was used for training too, see [docs/tpu.md](docs/tpu.md) for GCP setup, TPU factsheet, and single/multi-host workflows.
\ No newline at end of file
+```
+@misc{ndubuaku2026needle,
+ title={Needle},
+ author={Henry Ndubuaku and Jakub Mroz and Karen Mosoyan and Roman Shemet and Parkirat Sandhu and Satyajit Kumar and Noah Cylich and Justin H. Lee},
+ year={2026},
+ url={https://github.com/cactus-compute/needle}
+}
+```
\ No newline at end of file
diff --git a/docs/hf_model_card.md b/docs/hf_model_card.md
index 933b37a..c0e9975 100644
--- a/docs/hf_model_card.md
+++ b/docs/hf_model_card.md
@@ -89,10 +89,10 @@ Opens a web UI at http://127.0.0.1:7860 where you can test and finetune on your
## Usage (Python)
```python
-from needle import load_checkpoint, generate, EncoderDecoderTransformer, get_tokenizer
+from needle import load_checkpoint, generate, SimpleAttentionNetwork, get_tokenizer
params, config = load_checkpoint("checkpoints/needle.pkl")
-model = EncoderDecoderTransformer(config)
+model = SimpleAttentionNetwork(config)
tokenizer = get_tokenizer()
result = generate(
diff --git a/needle/training/eval.py b/needle/training/eval.py
index 330e157..1b0d1dc 100644
--- a/needle/training/eval.py
+++ b/needle/training/eval.py
@@ -9,7 +9,7 @@ import optax
from ..dataset.dataset import get_tokenizer, load_tool_calls, load_prepared_data, DEFAULT_MAX_ENC_LEN, DEFAULT_MAX_DEC_LEN, DEFAULT_MAX_GEN_LEN
from ..model.architecture import (
- EncoderDecoderTransformer,
+ SimpleAttentionNetwork,
TransformerConfig,
make_causal_mask,
make_causal_packing_mask,
@@ -540,7 +540,7 @@ def main(args):
import json as _json_mod
params, config = load_checkpoint(args.checkpoint)
- model = EncoderDecoderTransformer(config)
+ model = SimpleAttentionNetwork(config)
tokenizer = get_tokenizer()
param_count = sum(x.size for x in jax.tree.leaves(params))
diff --git a/needle/training/finetune.py b/needle/training/finetune.py
index 4774451..5702441 100644
--- a/needle/training/finetune.py
+++ b/needle/training/finetune.py
@@ -296,10 +296,10 @@ def finetune_local(args):
# Base model eval on TEST set (never seen by model)
from ..model.run import load_checkpoint
- from ..model.architecture import EncoderDecoderTransformer
+ from ..model.architecture import SimpleAttentionNetwork
print(f"Evaluating base model on {len(test_examples)} test examples...")
base_params, base_config = load_checkpoint(args.checkpoint)
- base_model = EncoderDecoderTransformer(base_config)
+ base_model = SimpleAttentionNetwork(base_config)
base_metrics = _quick_tool_eval(
base_model, base_params, tokenizer, test_examples,
max_gen_len=min(max_dec_len, 512), max_enc_len=max_enc_len,
@@ -344,7 +344,7 @@ def finetune_local(args):
if best_path and os.path.exists(best_path) and test_examples:
print(f"Evaluating finetuned model on {len(test_examples)} test examples...")
ft_params, ft_config = load_checkpoint(best_path)
- ft_model = EncoderDecoderTransformer(ft_config)
+ ft_model = SimpleAttentionNetwork(ft_config)
ft_metrics = _quick_tool_eval(
ft_model, ft_params, tokenizer, test_examples,
max_gen_len=min(max_dec_len, 512), max_enc_len=max_enc_len,
diff --git a/needle/training/pretrain.py b/needle/training/pretrain.py
index 668ff4d..6c1bf83 100644
--- a/needle/training/pretrain.py
+++ b/needle/training/pretrain.py
@@ -24,7 +24,7 @@ from tqdm import tqdm
from ..dataset.tokenizer import get_tokenizer, EOS_ID, TOOLS_ID, PAD_ID
from ..model.architecture import (
- EncoderDecoderTransformer,
+ SimpleAttentionNetwork,
TransformerConfig,
make_padding_mask,
make_causal_mask,
diff --git a/needle/ui/server.py b/needle/ui/server.py
index c980367..673e7ee 100644
--- a/needle/ui/server.py
+++ b/needle/ui/server.py
@@ -457,12 +457,12 @@ def _run_generate(query, tools, seed, max_gen_len, constrained):
def _load_checkpoint(path, display_name=None):
global _model, _params, _tokenizer, _current_model, _current_model_path
from ..dataset.dataset import get_tokenizer
- from ..model.architecture import EncoderDecoderTransformer
+ from ..model.architecture import SimpleAttentionNetwork
from ..model.run import load_checkpoint
with _lock:
_params, config = load_checkpoint(path)
- _model = EncoderDecoderTransformer(config)
+ _model = SimpleAttentionNetwork(config)
_tokenizer = get_tokenizer()
_current_model = display_name or Path(path).name
_current_model_path = path
@@ -763,13 +763,13 @@ def _resolve_checkpoint(checkpoint_arg):
def main(args):
global _model, _params, _tokenizer, _current_model, _current_model_path
from ..dataset.dataset import get_tokenizer
- from ..model.architecture import EncoderDecoderTransformer
+ from ..model.architecture import SimpleAttentionNetwork
from ..model.run import load_checkpoint
checkpoint_path = _resolve_checkpoint(args.checkpoint)
print(f"Loading checkpoint: {checkpoint_path}", file=sys.stderr)
_params, config = load_checkpoint(checkpoint_path)
- _model = EncoderDecoderTransformer(config)
+ _model = SimpleAttentionNetwork(config)
_tokenizer = get_tokenizer()
_current_model = Path(checkpoint_path).name
_current_model_path = checkpoint_path