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.

feat: support .safetensors format for checkpoints and adapters

HenryNdubuakufbba1f14d1dc
diff --git a/README.md b/README.md
index d407c57..9589d31 100644
--- a/README.md
+++ b/README.md
@@ -121,7 +121,7 @@ needle finetune data.jsonl --epochs 10
needle finetune data.jsonl --epochs 10 --generate 300 --lora-rank 16 --lora-alpha 32
```
-Key options: `--epochs` (default 3), `--lora-rank` (16), `--lora-alpha` (32), `--lr` (1e-4), `--batch-size` (16), `--max-len` (1024), `--val-split` (0.1), `--checkpoint <base.pkl>`, `--checkpoint-dir <dir>` (default `checkpoints`), `--out <adapter.pkl>`, `--generate <n>`, `--model <id>` (default `deepseek/deepseek-v4-flash`), and `--workers <n>` (default 8). `--generate` uses the configured OpenRouter endpoint to synthesize extra examples before training. The adapter is written to `checkpoints/needle_lora.pkl` by default. A validation loss prints each epoch from the held out split.
+Key options: `--epochs` (default 3), `--lora-rank` (16), `--lora-alpha` (32), `--lr` (1e-4), `--batch-size` (16), `--max-len` (1024), `--val-split` (0.1), `--checkpoint <base.safetensors or .pkl>`, `--checkpoint-dir <dir>` (default `checkpoints`), `--out <adapter.safetensors or .pkl>`, `--generate <n>`, `--model <id>` (default `deepseek/deepseek-v4-flash`), and `--workers <n>` (default 8). `--generate` uses the configured OpenRouter endpoint to synthesize extra examples before training. The adapter is written to `checkpoints/needle_lora.pkl` by default. A validation loss prints each epoch from the held out split.
Training is plain JAX and runs on any accelerator jax supports. On an NVIDIA machine install the CUDA build and the same command trains on the GPU:
@@ -138,7 +138,7 @@ pip install "cactus-needle[train,metal]"
**3. Build a tuned `.cact`.** Merge the adapter into the base and quantize. The base auto-downloads if absent.
```sh
-needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact
+needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.safetensors --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, and `needle download <platform>` (e.g. `macos-arm64`) fetches that platform's engine runner.
diff --git a/doc/apis.md b/doc/apis.md
index cbead42..474c8fe 100644
--- a/doc/apis.md
+++ b/doc/apis.md
@@ -168,7 +168,7 @@ Five or fewer declared tools render directly. Above that, retrieval engages: at
## Confidence
-The `confidence` field is the minimum of two signals: a calibrated post-hoc head that scores the full prompt plus the call the model just produced, and the decoding probability of the call tokens. A call is accepted only when both agree, so the failure mode is escalation, not wrong execution. The contract: pick a threshold for your product, act at or above it, re-ask or route to a bigger model below it. Off-topic requests return the empty call `[]`. Every response also carries `escalate`, true when `confidence` is below the engine's default threshold of 0.15.
+The `confidence` field is the minimum of two signals: a calibrated post-hoc head that scores the full prompt plus the call the model just produced, and the decoding probability of the call tokens. A call is accepted only when both agree, so the failure mode is escalation, not wrong execution. The contract: pick a threshold for your product, act at or above it, re-ask or route to a bigger model below it. Off-topic requests return the empty call `[]`. Every response also carries `escalate`, true when `confidence` is below the engine's default threshold of 0.1.
Calibration holds for the base model only. Fine-tuning does not update the head, so an agent running tuned weights reports `confidence` as `None` and warns once at construction.
diff --git a/doc/finetuning.md b/doc/finetuning.md
index 1085cef..26119cf 100644
--- a/doc/finetuning.md
+++ b/doc/finetuning.md
@@ -29,10 +29,12 @@ Rules that matter:
Train, export, load:
```sh
-needle finetune data.jsonl --epochs 10 --out adapter.pkl
-needle build checkpoints/needle2.pkl --lora adapter.pkl --out tuned.cact
+needle finetune data.jsonl --epochs 10 --out adapter.safetensors
+needle build checkpoints/needle2.pkl --lora adapter.safetensors --out tuned.cact
```
+Checkpoints and adapters are `.safetensors`; the Needle 2 base shipped as `checkpoints/needle2.pkl` and pickle files still load.
+
```python
agent = needle.Needle(tools=[...], weights="tuned.cact")
```
diff --git a/llms.txt b/llms.txt
index ae3fb2b..7a8d8d3 100644
--- a/llms.txt
+++ b/llms.txt
@@ -124,7 +124,7 @@ if r["type"] == "call":
## Confidence gating
-`confidence` is the min of a post-hoc calibration head and the decode probability of the call. Calibration holds for the base model only: an agent constructed with `weights=` reports `confidence` as None (fine-tuning does not update the head). Pick a threshold per product; act at/above it, escalate below it (`escalate` in the response applies the engine default of 0.15):
+`confidence` is the min of a post-hoc calibration head and the decode probability of the call. Calibration holds for the base model only: an agent constructed with `weights=` reports `confidence` as None (fine-tuning does not update the head). Pick a threshold per product; act at/above it, escalate below it (`escalate` in the response applies the engine default of 0.1):
```python
r = agent.complete(user_text)
@@ -166,7 +166,7 @@ pip install "cactus-needle[train]"
export OPENROUTER_API_KEY=sk-or-...
needle generate-data --tools my_tools.json --num-samples 500 --output data.jsonl # optional
needle finetune data.jsonl --epochs 3 --generate 300 # LoRA; auto-downloads base
-needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my.cact
+needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.safetensors --out my.cact
```
Run a tuned model - the engine is weights-agnostic:
@@ -176,7 +176,7 @@ agent = needle.Needle(weights="my.cact", tools=[...])
agent.run("...")
```
-Options: `finetune --lora-rank 16 --lora-alpha 32 --lr 1e-4 --batch-size 16 --max-len 1024 --val-split 0.1 --checkpoint <base.pkl> --checkpoint-dir <dir> --out <adapter.pkl> --generate <n> --model <id> --workers <n>`; `--model` defaults to `deepseek/deepseek-v4-flash`, `--workers` defaults to `8`, and `--checkpoint-dir` defaults to `checkpoints`. `--generate` synthesizes extra examples through the configured OpenRouter endpoint before training. `build --bits 2|4 --upload` (with `NEEDLE_HF_REPO=<you>/<model>`).
+Options: `finetune --lora-rank 16 --lora-alpha 32 --lr 1e-4 --batch-size 16 --max-len 1024 --val-split 0.1 --checkpoint <base.safetensors or .pkl> --checkpoint-dir <dir> --out <adapter.safetensors or .pkl> --generate <n> --model <id> --workers <n>`; `--model` defaults to `deepseek/deepseek-v4-flash`, `--workers` defaults to `8`, and `--checkpoint-dir` defaults to `checkpoints`. `--generate` synthesizes extra examples through the configured OpenRouter endpoint before training. `build --bits 2|4 --upload` (with `NEEDLE_HF_REPO=<you>/<model>`).
## Playground (browser)
@@ -200,7 +200,7 @@ Adapt by swapping the Literal values for your own and keeping the shapes: closed
## CLI summary
-- `needle run --checkpoint <base.pkl> --query "..." --tools tools.json` - JAX reference inference from a checkpoint (dev path; normal inference is the Python `Needle` API above).
+- `needle run --checkpoint <base.safetensors or .pkl> --query "..." --tools tools.json` - JAX reference inference from a checkpoint (dev path; normal inference is the Python `Needle` API above).
- `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.
@@ -212,7 +212,8 @@ Adapt by swapping the Literal values for your own and keeping the shapes: closed
- Do not read `arguments` keys that were not evidenced in the input; optional fields may be absent.
- Do not create one `Needle` per turn for a conversation; reuse the instance so context carries. New tools = new instance.
- `import needle` does not import JAX; only `needle finetune`/`build` do.
-- `weights=` expects a `.cact` (from `needle build`), not a `.pkl` checkpoint.
+- `weights=` expects a `.cact` (from `needle build`), not a `.safetensors` or `.pkl` checkpoint.
+- Checkpoints and adapters are `.safetensors`; only the Needle 2 base shipped as a `.pkl`, and both formats load.
- The engine cannot unload weights: once a tuned `.cact` is bound, constructing or calling a base-model agent raises instead of silently answering with those weights. Construct agents that want the base model before any tuned one, or run them in separate processes.
## Telemetry
diff --git a/needle/cli.py b/needle/cli.py
index 15dd39b..93b4fa5 100644
--- a/needle/cli.py
+++ b/needle/cli.py
@@ -149,7 +149,8 @@ def main():
p.add_argument("--workers", type=int, default=8,
help="Concurrent OpenRouter requests when generating (default: 8)")
p.add_argument("--checkpoint-dir", type=str, default="checkpoints")
- p.add_argument("--out", type=str, default=None, help="Output adapter path (.pkl)")
+ p.add_argument("--out", type=str, default=None,
+ help="Output adapter path (.safetensors, or .pkl)")
p.add_argument(
"--qat-bits", choices=["auto", "none", "2", "4"], default="auto",
help="LoRA training numerics: auto matches the checkpoint export scheme "
@@ -166,7 +167,8 @@ def main():
p.add_argument("--output", type=str, default=None)
p = sub.add_parser("build")
- p.add_argument("checkpoint", type=str, help="Base checkpoint (.pkl) to export")
+ p.add_argument("checkpoint", type=str,
+ help="Base checkpoint (.safetensors or .pkl) to export")
p.add_argument("--lora", type=str, default=None, help="LoRA adapter to merge before export")
p.add_argument("--out", type=str, default=None, help="Output .cact path")
p.add_argument("--upload", action="store_true", help="Push the .cact to $NEEDLE_HF_REPO")
diff --git a/needle/model/checkpoints.py b/needle/model/checkpoints.py
new file mode 100644
index 0000000..141ff61
--- /dev/null
+++ b/needle/model/checkpoints.py
@@ -0,0 +1,128 @@
+import json
+import os
+import pickle
+
+import numpy as np
+
+SAFETENSORS_SUFFIX = ".safetensors"
+
+
+def is_safetensors(path):
+ return os.fspath(path).endswith(SAFETENSORS_SUFFIX)
+
+
+def _contiguous(value):
+ array = np.asarray(value)
+ return np.ascontiguousarray(array) if array.ndim else array
+
+
+def flatten(tree, prefix=""):
+ flat = {}
+ for key, value in tree.items():
+ name = f"{prefix}/{key}" if prefix else str(key)
+ if isinstance(value, dict):
+ flat.update(flatten(value, name))
+ else:
+ flat[name] = _contiguous(value)
+ return flat
+
+
+def unflatten(flat):
+ tree = {}
+ for name, value in flat.items():
+ node = tree
+ parts = name.split("/")
+ for part in parts[:-1]:
+ node = node.setdefault(part, {})
+ node[parts[-1]] = value
+ return tree
+
+
+def _safetensors_numpy():
+ try:
+ from safetensors import numpy as safetensors_numpy
+ except ImportError as err:
+ raise ImportError("reading or writing .safetensors needs the safetensors package: "
+ "pip install safetensors") from err
+ return safetensors_numpy
+
+
+def _json_or_default(text, default):
+ if text in (None, ""):
+ return default
+ return json.loads(text)
+
+
+def _int_or_none(text):
+ if text in (None, ""):
+ return None
+ return int(text)
+
+
+def read_checkpoint(path):
+ if is_safetensors(path):
+ library = _safetensors_numpy()
+ from safetensors import safe_open
+
+ with safe_open(os.fspath(path), framework="np") as handle:
+ metadata = handle.metadata() or {}
+ return {
+ "format_version": _int_or_none(metadata.get("format_version")),
+ "params": unflatten(library.load_file(os.fspath(path))),
+ "config": _json_or_default(metadata.get("config"), {}),
+ "step": _int_or_none(metadata.get("step")),
+ "run": _json_or_default(metadata.get("run"), {}),
+ }
+ with open(path, "rb") as handle:
+ return pickle.load(handle)
+
+
+def write_checkpoint(path, checkpoint):
+ if is_safetensors(path):
+ library = _safetensors_numpy()
+ metadata = {
+ "format_version": str(checkpoint.get("format_version", "")),
+ "config": json.dumps(checkpoint.get("config", {}), default=str),
+ "step": "" if checkpoint.get("step") is None else str(checkpoint["step"]),
+ "run": json.dumps(checkpoint.get("run") or {}, default=str),
+ }
+ library.save_file(flatten(checkpoint["params"]), os.fspath(path), metadata=metadata)
+ return
+ with open(path, "wb") as handle:
+ pickle.dump(checkpoint, handle)
+
+
+_ADAPTER_FIELDS = ("scale", "base", "rank", "qat_bits", "qat_bits_map", "seed")
+
+
+def write_adapter(path, adapter):
+ if is_safetensors(path):
+ library = _safetensors_numpy()
+ tensors = {}
+ for name, value in adapter["lora"].items():
+ tensors[f"lora/{name}/A"] = _contiguous(value["A"])
+ tensors[f"lora/{name}/B"] = _contiguous(value["B"])
+ metadata = {key: json.dumps(adapter.get(key), default=str) for key in _ADAPTER_FIELDS}
+ library.save_file(tensors, os.fspath(path), metadata=metadata)
+ return
+ with open(path, "wb") as handle:
+ pickle.dump(adapter, handle)
+
+
+def read_adapter(path):
+ if is_safetensors(path):
+ library = _safetensors_numpy()
+ from safetensors import safe_open
+
+ with safe_open(os.fspath(path), framework="np") as handle:
+ metadata = handle.metadata() or {}
+ lora = {}
+ for name, value in library.load_file(os.fspath(path)).items():
+ _, key, matrix = name.rsplit("/", 2) if name.count("/") == 2 else (None, *name[5:].rsplit("/", 1))
+ lora.setdefault(key, {})[matrix] = value
+ adapter = {"lora": lora}
+ for key in _ADAPTER_FIELDS:
+ adapter[key] = _json_or_default(metadata.get(key), None)
+ return adapter
+ with open(path, "rb") as handle:
+ return pickle.load(handle)
diff --git a/needle/model/finetune.py b/needle/model/finetune.py
index 2f7ec37..5eca39c 100644
--- a/needle/model/finetune.py
+++ b/needle/model/finetune.py
@@ -1,7 +1,8 @@
import concurrent.futures
import json
import os
-import pickle
+
+from .checkpoints import read_adapter, write_adapter
import sys
import urllib.request
from concurrent.futures import ThreadPoolExecutor
@@ -426,18 +427,17 @@ def finetune_local(args, progress=None):
emit(f" {'epoch':<9} {epoch + 1}/{args.epochs} loss {last:.4f}")
os.makedirs(args.checkpoint_dir, exist_ok=True)
- out = args.out or os.path.join(args.checkpoint_dir, "needle_lora.pkl")
- with open(out, "wb") as handle:
- pickle.dump({
- "lora": {"/".join(p): {"A": np.asarray(v["A"]), "B": np.asarray(v["B"])}
- for p, v in lora.items()},
- "scale": float(scale),
- "base": base_path,
- "rank": args.lora_rank,
- "qat_bits": qat_bits,
- "qat_bits_map": qat_bits_map,
- "seed": seed,
- }, handle)
+ out = args.out or os.path.join(args.checkpoint_dir, "needle_lora.safetensors")
+ write_adapter(out, {
+ "lora": {"/".join(p): {"A": np.asarray(v["A"]), "B": np.asarray(v["B"])}
+ for p, v in lora.items()},
+ "scale": float(scale),
+ "base": base_path,
+ "rank": args.lora_rank,
+ "qat_bits": qat_bits,
+ "qat_bits_map": qat_bits_map,
+ "seed": seed,
+ })
print(f" {'adapter':<9} {out}")
print(f" {'next':<9} needle build {base_path} --lora {out}")
print(f" {'note':<9} confidence reports None with tuned weights; the head is not tuned")
@@ -454,8 +454,7 @@ def build_main(args):
adapter_qat_bits = None
adapter_qat_bits_map = None
if args.lora:
- with open(args.lora, "rb") as handle:
- adapter = pickle.load(handle)
+ adapter = read_adapter(args.lora)
lora = {tuple(key.split("/")): {"A": jnp.asarray(v["A"]), "B": jnp.asarray(v["B"])}
for key, v in adapter["lora"].items()}
params = merge_lora(params, lora, adapter["scale"])
diff --git a/needle/model/run.py b/needle/model/run.py
index b65ce5a..c5e92ca 100644
--- a/needle/model/run.py
+++ b/needle/model/run.py
@@ -1,6 +1,5 @@
import os
import json
-import pickle
import re
import sys
@@ -10,6 +9,7 @@ import numpy as np
from .tokenizer import get_tokenizer, BOS_ID, EOS_ID, PAD_ID
from .architecture import SimpleAttentionNetwork, TransformerConfig
+from .checkpoints import read_checkpoint, write_checkpoint
CHECKPOINT_FORMAT_VERSION = 2
BUF_BUCKET = 128
@@ -29,8 +29,7 @@ def average_checkpoints(paths, out):
scale = 1.0 / len(paths)
for p in paths:
- with open(p, "rb") as f:
- ckpt = pickle.load(f)
+ ckpt = read_checkpoint(p)
if ckpt.get("format_version") != CHECKPOINT_FORMAT_VERSION:
raise ValueError(f"{p} is not a format-v{CHECKPOINT_FORMAT_VERSION} checkpoint")
acc = acc if acc is not None else {}
@@ -42,14 +41,13 @@ def average_checkpoints(paths, out):
return {k: to_fp16(v) if isinstance(v, dict) else v.astype(np.float16)
for k, v in t.items()}
- with open(out, "wb") as f:
- pickle.dump({
- "format_version": CHECKPOINT_FORMAT_VERSION,
- "params": to_fp16(acc),
- "config": meta["config"],
- "step": meta.get("step"),
- "run": {**(meta.get("run") or {}), "averaged_from": steps},
- }, f)
+ write_checkpoint(out, {
+ "format_version": CHECKPOINT_FORMAT_VERSION,
+ "params": to_fp16(acc),
+ "config": meta["config"],
+ "step": meta.get("step"),
+ "run": {**(meta.get("run") or {}), "averaged_from": steps},
+ })
print(f"Averaged {len(paths)} checkpoints (steps {steps}) -> {out}")
@@ -72,6 +70,9 @@ def load_checkpoint(path, return_run=False):
flat = "checkpoints/" + os.path.basename(path)
if flat not in names:
names.append(flat)
+ root = os.path.basename(path)
+ if root not in names:
+ names.append(root)
err = None
for name in names:
try:
@@ -81,8 +82,7 @@ def load_checkpoint(path, return_run=False):
err = e
else:
raise err
- with open(path, "rb") as f:
- ckpt = pickle.load(f)
+ ckpt = read_checkpoint(path)
version = ckpt.get("format_version") if isinstance(ckpt, dict) else None
if version != CHECKPOINT_FORMAT_VERSION:
raise ValueError(
diff --git a/needle/playground/server.py b/needle/playground/server.py
index 6525fe6..3428ece 100644
--- a/needle/playground/server.py
+++ b/needle/playground/server.py
@@ -79,7 +79,7 @@ def _finetune_worker(tools_json, api_key, samples, engine):
handle.write(json.dumps(row) + "\n")
_FT["step"] = "training"
- adapter = str(_DOWNLOADS / "needle_playground_lora.pkl")
+ adapter = str(_DOWNLOADS / "needle_playground_lora.safetensors")
finetune_local(types.SimpleNamespace(
jsonl_path=data_path, checkpoint=None, epochs=3, batch_size=16, lr=1e-4,
lora_rank=16, lora_alpha=32.0, max_len=1024, generate=0, model=None,
diff --git a/pyproject.toml b/pyproject.toml
index 6d1e95a..47a8c0a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -16,6 +16,7 @@ train = [
"jaxlib",
"flax>=0.10.2",
"optax",
+ "safetensors",
"sentencepiece"
]
gpu = ["jax[cuda12]"]
diff --git a/requirements-train.txt b/requirements-train.txt
index 3b6ac3f..5035c8a 100644
--- a/requirements-train.txt
+++ b/requirements-train.txt
@@ -6,4 +6,5 @@ jax
jaxlib
flax>=0.10.2
optax
-sentencepiece
\ No newline at end of file
+safetensors
+sentencepiece
diff --git a/tests/conftest.py b/tests/conftest.py
index 26b1d8e..7b2c715 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -62,3 +62,12 @@ def tiny_checkpoint(tmp_path_factory):
pickle.dump({"format_version": 2, "params": params,
"config": dict(vars(config))}, handle)
return str(path)
+
+
[email protected](scope="session")
+def tiny_checkpoint_safetensors(tiny_checkpoint, tmp_path_factory):
+ from needle.model.checkpoints import read_checkpoint, write_checkpoint
+
+ path = tmp_path_factory.mktemp("ckpt") / "tiny.safetensors"
+ write_checkpoint(path, read_checkpoint(tiny_checkpoint))
+ return str(path)
diff --git a/tests/test_build.py b/tests/test_build.py
index a1835f8..049e498 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -57,3 +57,21 @@ def test_export_round_trips_a_projection(tiny_checkpoint, tmp_path):
dequant = tensors[2]
assert dequant.shape == original.shape
assert np.corrcoef(dequant.ravel(), original.ravel())[0, 1] > 0.9
+
+
+def test_build_from_safetensors_checkpoint(tiny_checkpoint, tiny_checkpoint_safetensors, tmp_path):
+ from needle.model.finetune import build_main
+ from needle.model.export import read_export
+ from needle.model.run import load_checkpoint
+ import numpy as np
+ import jax
+
+ a, cfg_a = load_checkpoint(tiny_checkpoint)
+ b, cfg_b = load_checkpoint(tiny_checkpoint_safetensors)
+ assert vars(cfg_a) == vars(cfg_b)
+ assert all(np.array_equal(np.asarray(x), np.asarray(y))
+ for x, y in zip(jax.tree_util.tree_leaves(a), jax.tree_util.tree_leaves(b)))
+ out = str(tmp_path / "from_safetensors.cact")
+ build_main(_build_args(tiny_checkpoint_safetensors, out, bits="4"))
+ header, _ = read_export(out)
+ assert header["num_tensors"] > 0
diff --git a/tests/test_finetune.py b/tests/test_finetune.py
index 3392b8f..e45a8a7 100644
--- a/tests/test_finetune.py
+++ b/tests/test_finetune.py
@@ -153,3 +153,27 @@ def test_finetune_adapter_records_realized_seed(tiny_checkpoint, tmp_path):
with out.open("rb") as handle:
adapter = pickle.load(handle)
assert adapter["seed"] == 17
+
+
+def test_finetune_adapter_defaults_to_safetensors_and_builds(tiny_checkpoint_safetensors, tmp_path):
+ from needle.model.finetune import finetune_local, build_main
+ from needle.model.checkpoints import read_adapter
+ from needle.model.export import read_export
+
+ data = tmp_path / "data.jsonl"
+ _write_data(data)
+ args = _finetune_args(data, tiny_checkpoint_safetensors, "", tmp_path / "ck")
+ args.out = None
+ finetune_local(args)
+ adapter_path = tmp_path / "ck" / "needle_lora.safetensors"
+ assert adapter_path.exists()
+ adapter = read_adapter(adapter_path)
+ assert adapter["rank"] == 4 and abs(adapter["scale"] - 2.0) < 1e-6
+ assert adapter["base"] == tiny_checkpoint_safetensors
+ assert adapter["lora"] and all("A" in v and "B" in v for v in adapter["lora"].values())
+
+ out = str(tmp_path / "merged_st.cact")
+ build_main(types.SimpleNamespace(checkpoint=tiny_checkpoint_safetensors,
+ lora=str(adapter_path), out=out, upload=False, bits="4"))
+ header, _ = read_export(out)
+ assert header["num_tensors"] > 0
diff --git a/tests/test_run.py b/tests/test_run.py
index ce9159d..75e4c3f 100644
--- a/tests/test_run.py
+++ b/tests/test_run.py
@@ -1,3 +1,4 @@
+import pytest
import argparse
import json
@@ -39,3 +40,21 @@ def test_main_loads_tools_file_and_runs(tiny_checkpoint, tmp_path, capsys):
assert "<tools>" in out
assert '"name":"f"' in out
+
+
+def test_missing_checkpoint_is_looked_up_under_checkpoints_then_at_the_repo_root(monkeypatch, tmp_path):
+ from huggingface_hub.errors import EntryNotFoundError
+ import huggingface_hub
+ from needle.model import run
+
+ attempted = []
+
+ def fake_download(repo, name, repo_type, local_dir):
+ attempted.append(name)
+ raise EntryNotFoundError("missing")
+
+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", fake_download)
+ monkeypatch.chdir(tmp_path)
+ with pytest.raises(EntryNotFoundError):
+ run.load_checkpoint("needle3.safetensors")
+ assert attempted == ["checkpoints/needle3.safetensors", "needle3.safetensors"]