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.

docs: document the platform mode of needle download (engine runner) (#83)

LeonSGP571fcd68f48b
diff --git a/README.md b/README.md
index 377100a..0ee4db8 100644
--- a/README.md
+++ b/README.md
@@ -121,7 +121,7 @@ pip install "cactus-needle[metal]"
needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact
```
-Add `--bits 2` for a smaller model (by default the export follows the checkpoint's declared per-layer bit map, falling back to 4 when the checkpoint declares none), or set `NEEDLE_HF_REPO=<you>/<model>` and pass `--upload` to publish the `.cact`. The counterpart `needle download <you>/<model>/my_needle.cact` pulls a published archive on any machine.
+Add `--bits 2` for a smaller model (by default the export follows the checkpoint's declared per-layer bit map, falling back to 4 when the checkpoint declares none), or set `NEEDLE_HF_REPO=<you>/<model>` and pass `--upload` to publish the `.cact`. The counterpart `needle download <you>/<model>/my_needle.cact` pulls a published archive on any machine, and `needle download <platform>` (e.g. `macos-arm64`) fetches that platform's engine runner.
**4. Run it.** The engine is weights-agnostic, so a tuned `.cact` runs on it directly - no recompilation:
diff --git a/doc/apis.md b/doc/apis.md
index 10f7e55..77ecd13 100644
--- a/doc/apis.md
+++ b/doc/apis.md
@@ -157,7 +157,7 @@ Calibration holds for the base model only. Fine-tuning does not update the head,
The engine is fetched once and cached at `~/.cache/cactus-needle/<engine version>/`. Inference itself never touches the network, so an air gapped device only needs that one file in place. Three ways to get it there:
-1. `needle fetch` downloads the engine for the current machine into the cache and prints the path. `--out <dir>` places it elsewhere. `--platform-tag manylinux2014_aarch64` fetches the build for a different device; tags follow the wheel names on the Hugging Face repo (`macosx_11_0_arm64`, `manylinux2014_x86_64`, `musllinux_1_2_aarch64`, `win_amd64`, `win_arm64`).
+1. `needle fetch` downloads the engine for the current machine into the cache and prints the path. `--out <dir>` places it elsewhere. `--platform-tag manylinux2014_aarch64` fetches the build for a different device; tags follow the wheel names on the Hugging Face repo (`macosx_11_0_arm64`, `manylinux2014_x86_64`, `musllinux_1_2_aarch64`, `win_amd64`, `win_arm64`). For the standalone engine runner, `needle download <platform> [--out <dir>]` (platform folder names like `macos-arm64`, `linux-x86_64`; the CLI prints the full list on an invalid name) copies that platform's engine files into `<out>/<platform>/` and marks the `needle` runner executable.
2. Copy the file to the same cache path on the device, or drop it inside the installed `needle/` package directory, which wins over the cache.
3. Set `NEEDLE_LIB_PATH=/path/to/libneedle.so` to load exactly that file and skip every lookup.
diff --git a/llms.txt b/llms.txt
index 343932e..9c69520 100644
--- a/llms.txt
+++ b/llms.txt
@@ -190,7 +190,7 @@ Preset demos, editable tools/prompt, multi-turn follow-ups, and a "Finetune on t
- `needle generate-data` / `needle finetune` / `needle build` - the fine-tuning pipeline.
- `needle playground` - browser UI.
- `needle fetch [--platform-tag <tag>] [--out <dir>]` - pre-download the inference engine for this machine (or another platform) into the cache; prints the path. For air-gapped devices, also see `NEEDLE_LIB_PATH` and `HF_HUB_OFFLINE` in doc/apis.md.
-- `needle download <org>/<repo>[/<file>.cact] [--out <dir>]` - pull a published `.cact` (single-archive repos need only `<org>/<repo>`).
+- `needle download <org>/<repo>[/<file>.cact] | <platform> [--out <dir>]` - pull a published `.cact` (single-archive repos need only `<org>/<repo>`), or pass a platform folder name (`macos-arm64`, `linux-x86_64`, ...) to fetch that platform's engine files (including the `needle` runner, marked executable) into `<out>/<platform>/`.
## Common mistakes to avoid