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.mdindex 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_tokenizerparams, 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 filediff --git a/docs/hf_model_card.md b/docs/hf_model_card.mdindex 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_tokenizerparams, 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.pyindex 330e157..1b0d1dc 100644--- a/needle/training/eval.py+++ b/needle/training/eval.py@@ -9,7 +9,7 @@ import optaxfrom ..dataset.dataset import get_tokenizer, load_tool_calls, load_prepared_data, DEFAULT_MAX_ENC_LEN, DEFAULT_MAX_DEC_LEN, DEFAULT_MAX_GEN_LENfrom ..model.architecture import (- EncoderDecoderTransformer,+ SimpleAttentionNetwork,TransformerConfig,make_causal_mask,make_causal_packing_mask,@@ -540,7 +540,7 @@ def main(args):import json as _json_modparams, 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.pyindex 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 SimpleAttentionNetworkprint(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.pyindex 668ff4d..6c1bf83 100644--- a/needle/training/pretrain.py+++ b/needle/training/pretrain.py@@ -24,7 +24,7 @@ from tqdm import tqdmfrom ..dataset.tokenizer import get_tokenizer, EOS_ID, TOOLS_ID, PAD_IDfrom ..model.architecture import (- EncoderDecoderTransformer,+ SimpleAttentionNetwork,TransformerConfig,make_padding_mask,make_causal_mask,diff --git a/needle/ui/server.py b/needle/ui/server.pyindex 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_pathfrom ..dataset.dataset import get_tokenizer- from ..model.architecture import EncoderDecoderTransformer+ from ..model.architecture import SimpleAttentionNetworkfrom ..model.run import load_checkpointwith _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_pathfrom ..dataset.dataset import get_tokenizer- from ..model.architecture import EncoderDecoderTransformer+ from ..model.architecture import SimpleAttentionNetworkfrom ..model.run import load_checkpointcheckpoint_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