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: refactor build process and update related functions; improve error handling and documentation

jakmro84e857423574
diff --git a/llms.txt b/llms.txt
index 265e459..8c14d33 100644
--- a/llms.txt
+++ b/llms.txt
@@ -209,7 +209,7 @@ Run a tuned model:
needle.transcribe("clip.wav", weights="my.cact")
```
-Options: `whistle finetune --language <code> --tokens <file> --epochs 3 --lora-rank 16 --lora-alpha 32 --lr 1e-4 --batch-size 16 --checkpoint <base.safetensors> --checkpoint-dir <dir> --out <adapter.safetensors>`; `--language` fills lines without one, `--tokens` is a file of words or characters to add to the vocabulary, one per line, and `--checkpoint-dir` defaults to `checkpoints`. Clips over 30 s are skipped. The run prints the validation loss after every epoch and ends with the test set's word error rate (character error rate for Chinese, Japanese, Korean and Thai), a quick greedy decode on the 4-bit weights; for real-world numbers, build the `.cact` and transcribe the test set with it. `whistle build --layers N --upload` (with `NEEDLE_HF_REPO=<you>/<model>`).
+Options: `whistle finetune --language <code> --tokens <file> --epochs 3 --lora-rank 16 --lora-alpha 32 --lr 1e-4 --batch-size 16 --checkpoint <base.safetensors> --checkpoint-dir <dir> --out <adapter.safetensors>`; `--language` fills lines without one, `--tokens` is a file of words or characters to add to the vocabulary, one per line, and `--checkpoint-dir` defaults to `checkpoints`. Clips over 30 s and empty transcripts are skipped. The run prints the validation loss after every epoch and ends with the test set's word error rate (character error rate for Chinese, Japanese, Korean and Thai), a quick greedy decode on the 4-bit weights; for real-world numbers, build the `.cact` and transcribe the test set with it. `whistle build --layers N --upload` (with `NEEDLE_HF_REPO=<you>/<model>`).
## Platform (hosted fine-tuning)
diff --git a/needle/__init__.py b/needle/__init__.py
index c389371..81aec5a 100644
--- a/needle/__init__.py
+++ b/needle/__init__.py
@@ -168,11 +168,13 @@ def _lib(generation=2):
lib = _load_cdll(generation)
lib.needle_init.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p]
lib.needle_init.restype = ctypes.c_int
- lib.needle_complete.argtypes = [
- ctypes.c_char_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int,
- ctypes.c_int, ctypes.c_char_p, ctypes.c_int]
lib.needle_complete.restype = ctypes.c_int
- if generation >= 3:
+ if generation < 3:
+ lib.needle_complete.argtypes = [ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_int]
+ else:
+ lib.needle_complete.argtypes = [
+ ctypes.c_char_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int,
+ ctypes.c_int, ctypes.c_char_p, ctypes.c_int]
lib.needle_embed.argtypes = [
ctypes.c_char_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int,
ctypes.POINTER(ctypes.c_float), ctypes.c_int]
@@ -288,8 +290,9 @@ class Needle:
raw = self._worker.complete(text, max_new_tokens)
else:
lib = _lib(self._generation)
+ audio = (None, 0) if self._generation >= 3 else ()
rc = lib.needle_complete(
- text.encode("utf-8"), None, 0, int(max_new_tokens), self._buffer,
+ text.encode("utf-8"), *audio, int(max_new_tokens), self._buffer,
len(self._buffer))
if rc < 0:
detail = self._buffer.value.decode("utf-8", "replace")
diff --git a/needle/_worker.py b/needle/_worker.py
index 4e461a9..2ad772f 100644
--- a/needle/_worker.py
+++ b/needle/_worker.py
@@ -52,13 +52,17 @@ def _load_library(path, generation=2):
lib.needle_init.argtypes = [ctypes.c_char_p, ctypes.c_char_p,
ctypes.c_char_p]
lib.needle_init.restype = ctypes.c_int
- lib.needle_complete.argtypes = [ctypes.c_char_p, ctypes.POINTER(ctypes.c_float),
- ctypes.c_int, ctypes.c_int,
- ctypes.c_char_p, ctypes.c_int]
lib.needle_complete.restype = ctypes.c_int
- if int(generation) >= 3:
+ if int(generation) < 3:
+ lib.needle_complete.argtypes = [ctypes.c_char_p, ctypes.c_int,
+ ctypes.c_char_p, ctypes.c_int]
+ else:
+ lib.needle_complete.argtypes = [ctypes.c_char_p, ctypes.POINTER(ctypes.c_float),
+ ctypes.c_int, ctypes.c_int,
+ ctypes.c_char_p, ctypes.c_int]
lib.needle_embed.argtypes = [
- ctypes.c_char_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
+ ctypes.c_char_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int,
+ ctypes.POINTER(ctypes.c_float), ctypes.c_int]
lib.needle_embed.restype = ctypes.c_int
lib.needle_reset.argtypes = []
lib.needle_reset.restype = None
@@ -96,8 +100,9 @@ def _child():
break
operation = request.get("operation")
if operation == "complete":
+ audio = (None, 0) if generation >= 3 else ()
code = lib.needle_complete(
- request["text"].encode("utf-8"), None, 0,
+ request["text"].encode("utf-8"), *audio,
int(request["max_new_tokens"]), output, len(output))
if code < 0:
_write_message(protocol, {
@@ -117,7 +122,7 @@ def _child():
})
continue
text = request["text"].encode("utf-8")
- dim = lib.needle_embed(text, None, 0)
+ dim = lib.needle_embed(text, None, 0, None, 0)
if dim <= 0:
_write_message(protocol, {
"status": "error",
@@ -125,7 +130,7 @@ def _child():
})
continue
embedding = (ctypes.c_float * dim)()
- code = lib.needle_embed(text, embedding, dim)
+ code = lib.needle_embed(text, None, 0, embedding, dim)
if code != dim:
_write_message(protocol, {
"status": "error",
diff --git a/needle/agent/tools.py b/needle/agent/tools.py
index 054436a..a68618b 100644
--- a/needle/agent/tools.py
+++ b/needle/agent/tools.py
@@ -1,3 +1,5 @@
+from __future__ import annotations
+
import enum
import inspect
import re
diff --git a/needle/agent/whistle.py b/needle/agent/whistle.py
index 4f7ec0f..00e474f 100644
--- a/needle/agent/whistle.py
+++ b/needle/agent/whistle.py
@@ -103,7 +103,7 @@ def _read_wav(path):
import numpy
import soxr
except ImportError:
- raise RuntimeError(f"resampling {rate} Hz audio to {SAMPLE_RATE} Hz needs soxr: pip install cactus-needle[mic]") from None
+ raise RuntimeError(f'resampling {rate} Hz audio to {SAMPLE_RATE} Hz needs soxr: pip install "cactus-needle[mic]"') from None
return soxr.resample(numpy.asarray(mono, numpy.float32), rate, SAMPLE_RATE, quality="HQ")
diff --git a/needle/cli.py b/needle/cli.py
index f91dddb..5958bcf 100644
--- a/needle/cli.py
+++ b/needle/cli.py
@@ -339,7 +339,7 @@ def main():
from .model.finetune import generate_main
generate_main(args)
elif args.command == "build":
- from .model.finetune import build_main
+ from .model.build import build_main
build_main(args)
elif args.command == "download":
import shutil
diff --git a/needle/model/build.py b/needle/model/build.py
new file mode 100644
index 0000000..8c54f7c
--- /dev/null
+++ b/needle/model/build.py
@@ -0,0 +1,78 @@
+import os
+import shutil
+
+from ..agent import fetch
+
+
+def build_main(args):
+ layers = getattr(args, "layers", None)
+ if args.lora or layers:
+ from .finetune import DEFAULT_BASE, merge_lora, rung
+ import jax.numpy as jnp
+ from .architecture import ConfidenceHead, effective_kv_window
+ from .checkpoints import read_adapter
+ from .export import read_layers, read_tokenizer_blob, write_export
+ from .quantize import WEIGHT_BITS
+ from .run import load_checkpoint
+
+ base_archive = fetch.fetch_weights(3, force=True)
+ print(f" {'base':<9} {base_archive} {os.path.getsize(base_archive) / 1e6:.2f} MB")
+ platform = getattr(args, "platform", None)
+ folder = None
+ if platform:
+ folder = os.path.abspath(args.out or platform)
+ for path in fetch.download_platform(platform, os.path.dirname(folder), generation=3, dest=folder):
+ print(f" {'engine':<9} {path} {os.path.getsize(path) / 1e6:.2f} MB")
+ out = os.path.join(folder, fetch.base_weights(3))
+ else:
+ out = args.out
+ if not args.lora and (not layers or layers == read_layers(base_archive)):
+ if not out:
+ raise SystemExit("pass --out <archive.cact>, or --platform to build a runnable folder")
+ shutil.copyfile(base_archive, out)
+ print(f" {'wrote':<9} {out} {os.path.getsize(out) / 1e6:.2f} MB the published base archive")
+ else:
+ adapter = read_adapter(args.lora) if args.lora else None
+ if adapter and adapter.get("languages") is not None:
+ raise SystemExit(f"{args.lora} is a Whistle adapter; build it with needle whistle build")
+ checkpoint = args.checkpoint
+ if not checkpoint and adapter and adapter.get("base") and os.path.exists(adapter["base"]):
+ checkpoint = adapter["base"]
+ checkpoint = checkpoint or DEFAULT_BASE
+ params, config, _ = load_checkpoint(checkpoint, return_run=True)
+ if 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"])
+ print(f" {'merged':<9} {len(lora)} weight groups {args.lora}")
+ if ConfidenceHead.key in params:
+ params = {k: v for k, v in params.items() if k != ConfidenceHead.key}
+ print(f" {'dropped':<9} the confidence head; it is not trained locally, so confidence reports None")
+ params, config = rung(params, config, layers)
+ print(f" {'depth':<9} {config.num_layers} layers")
+ out = out or (os.path.splitext(os.path.basename(checkpoint))[0] + ".cact")
+ info = write_export(params, config, out, bits=WEIGHT_BITS,
+ tokenizer=read_tokenizer_blob(base_archive),
+ kv_window=effective_kv_window(config))
+ print(f" {'wrote':<9} {info['path']} {info['bytes'] / 1e6:.2f} MB {info['tensors']} tensors W{WEIGHT_BITS}A8")
+ if folder:
+ runner = next((n for n in ("needle", "needle.exe") if os.path.exists(os.path.join(folder, n))), None)
+ if runner:
+ print(f" {'next':<9} {os.path.join(folder, runner)} --model {os.path.basename(out)} --tools tools.json --serve")
+ else:
+ print(f" {'next':<9} needle.Needle(weights={out!r}, tools=[...])")
+
+ if args.upload:
+ upload_archive(out)
+
+
+def upload_archive(out):
+ repo = os.environ.get("NEEDLE_HF_REPO")
+ if not repo:
+ raise SystemExit("set NEEDLE_HF_REPO=<you>/<model> to upload")
+ from huggingface_hub import HfApi
+ api = HfApi()
+ api.create_repo(repo, repo_type="model", exist_ok=True)
+ api.upload_file(path_or_fileobj=out, path_in_repo=os.path.basename(out),
+ repo_id=repo, repo_type="model")
+ print(f" {'uploaded':<9} {os.path.basename(out)} {repo}")
diff --git a/needle/model/finetune.py b/needle/model/finetune.py
index a5d49f5..09fa437 100644
--- a/needle/model/finetune.py
+++ b/needle/model/finetune.py
@@ -2,7 +2,7 @@ import concurrent.futures
import json
import os
-from .checkpoints import read_adapter, write_adapter
+from .checkpoints import write_adapter
import sys
import urllib.request
from concurrent.futures import ThreadPoolExecutor
@@ -507,76 +507,3 @@ def finetune_local(args, progress=None):
print(f" {'adapter':<9} {out}")
print(f" {'next':<9} needle build {base_path} --lora {out}")
print(f" {'note':<9} local tuning leaves the confidence head untrained; needle build drops it and confidence reports None")
-
-
-def build_main(args):
- import shutil
- import jax.numpy as jnp
- from ..agent import fetch
- from .run import load_checkpoint
- from .architecture import ConfidenceHead, effective_kv_window
- from .export import read_layers, read_tokenizer_blob, write_export
- from .quantize import WEIGHT_BITS
-
- base_archive = fetch.fetch_weights(3, force=True)
- print(f" {'base':<9} {base_archive} {os.path.getsize(base_archive) / 1e6:.2f} MB")
- platform = getattr(args, "platform", None)
- layers = getattr(args, "layers", None)
- folder = None
- if platform:
- folder = os.path.abspath(args.out or platform)
- for path in fetch.download_platform(platform, os.path.dirname(folder), generation=3, dest=folder):
- print(f" {'engine':<9} {path} {os.path.getsize(path) / 1e6:.2f} MB")
- out = os.path.join(folder, fetch.base_weights(3))
- else:
- out = args.out
- if not args.lora and (not layers or layers == read_layers(base_archive)):
- if not out:
- raise SystemExit("pass --out <archive.cact>, or --platform to build a runnable folder")
- shutil.copyfile(base_archive, out)
- print(f" {'wrote':<9} {out} {os.path.getsize(out) / 1e6:.2f} MB the published base archive")
- else:
- adapter = read_adapter(args.lora) if args.lora else None
- if adapter and adapter.get("languages") is not None:
- raise SystemExit(f"{args.lora} is a Whistle adapter; build it with needle whistle build")
- checkpoint = args.checkpoint
- if not checkpoint and adapter and adapter.get("base") and os.path.exists(adapter["base"]):
- checkpoint = adapter["base"]
- checkpoint = checkpoint or DEFAULT_BASE
- params, config, _ = load_checkpoint(checkpoint, return_run=True)
- if 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"])
- print(f" {'merged':<9} {len(lora)} weight groups {args.lora}")
- if ConfidenceHead.key in params:
- params = {k: v for k, v in params.items() if k != ConfidenceHead.key}
- print(f" {'dropped':<9} the confidence head; it is not trained locally, so confidence reports None")
- params, config = rung(params, config, layers)
- print(f" {'depth':<9} {config.num_layers} layers")
- out = out or (os.path.splitext(os.path.basename(checkpoint))[0] + ".cact")
- info = write_export(params, config, out, bits=WEIGHT_BITS,
- tokenizer=read_tokenizer_blob(base_archive),
- kv_window=effective_kv_window(config))
- print(f" {'wrote':<9} {info['path']} {info['bytes'] / 1e6:.2f} MB {info['tensors']} tensors W{WEIGHT_BITS}A8")
- if folder:
- runner = next((n for n in ("needle", "needle.exe") if os.path.exists(os.path.join(folder, n))), None)
- if runner:
- print(f" {'next':<9} {os.path.join(folder, runner)} --model {os.path.basename(out)} --tools tools.json --serve")
- else:
- print(f" {'next':<9} needle.Needle(weights={out!r}, tools=[...])")
-
- if args.upload:
- upload_archive(out)
-
-
-def upload_archive(out):
- repo = os.environ.get("NEEDLE_HF_REPO")
- if not repo:
- raise SystemExit("set NEEDLE_HF_REPO=<you>/<model> to upload")
- from huggingface_hub import HfApi
- api = HfApi()
- api.create_repo(repo, repo_type="model", exist_ok=True)
- api.upload_file(path_or_fileobj=out, path_in_repo=os.path.basename(out),
- repo_id=repo, repo_type="model")
- print(f" {'uploaded':<9} {os.path.basename(out)} {repo}")
diff --git a/needle/model/whistle_finetune.py b/needle/model/whistle_finetune.py
index 3e2a8bf..0ea7dd6 100644
--- a/needle/model/whistle_finetune.py
+++ b/needle/model/whistle_finetune.py
@@ -6,7 +6,7 @@ from dataclasses import replace
import numpy as np
-from .checkpoints import read_adapter, write_adapter
+from .checkpoints import is_safetensors, read_adapter, write_adapter
from .finetune import _training_rng, init_lora, lora_target_paths, merge_lora
from .whistle import LANGUAGES, Whistle, load_whistle
@@ -101,7 +101,7 @@ def read_audio(path):
import soxr
except ImportError:
raise RuntimeError(f"{path} is {rate} Hz; resampling it to {SAMPLE_RATE} Hz needs soxr: "
- "pip install cactus-needle[train]") from None
+ 'pip install "cactus-needle[train]"') from None
samples = soxr.resample(samples, rate, SAMPLE_RATE, quality="HQ")
return samples.astype(np.float32)
@@ -260,6 +260,9 @@ def finetune_main(args):
if args.epochs < 1 or args.batch_size < 1:
raise SystemExit("--epochs and --batch-size must be at least 1")
+ out = args.out or os.path.join(args.checkpoint_dir, "whistle_lora.safetensors")
+ if not is_safetensors(out):
+ raise SystemExit(f"--out must be a .safetensors file, got {out}")
base_path = args.checkpoint or DEFAULT_BASE
params, cfg = load_base(base_path)
params = jax.tree.map(lambda a: np.asarray(a).astype(np.float32), params)
@@ -276,8 +279,11 @@ def finetune_main(args):
raise SystemExit("no usable clips in " + path)
splits.append(clips)
skipped += dropped
- codes = {lang for clips in splits for *_, lang in clips}
+ codes = {lang for *_, lang in splits[0]}
languages = tuple(cfg.languages) + tuple(sorted(codes - set(cfg.languages)))
+ untrained = {lang for clips in splits[1:] for *_, lang in clips} - set(languages)
+ if untrained:
+ raise SystemExit(f"no training clips for {', '.join(sorted(untrained))}")
tokens = read_tokens(args.tokens) if args.tokens else []
pieces = token_pieces(WhistleTokenizer().sp, tokens)
tokenizer = WhistleTokenizer(pieces, languages)
@@ -302,8 +308,9 @@ def finetune_main(args):
items, validation, test = ([item for item in clips if len(item[1]) <= cfg.max_tokens + 1] for clips in encoded)
if long:
print(f" {'skipped':<9} {long} clips with transcripts over {cfg.max_tokens} tokens")
- if not items:
- raise SystemExit("no clips left to train on")
+ for path, clips in zip((args.train, args.validation, args.test), (items, validation, test)):
+ if not clips:
+ raise SystemExit("no usable clips in " + path)
if tokens:
found = sum(any(token in text for *_, text in items) for token in tokens)
print(f" {'tokens':<9} {found}/{len(tokens)} appear in the transcripts")
@@ -370,8 +377,7 @@ def finetune_main(args):
f"greedy decoding on the W{WEIGHT_BITS} weights")
print(f" {'note':<9} for real-world numbers, build the .cact and transcribe the test set with it")
- os.makedirs(args.checkpoint_dir, exist_ok=True)
- out = args.out or os.path.join(args.checkpoint_dir, "whistle_lora.safetensors")
+ os.makedirs(os.path.dirname(os.path.abspath(out)), exist_ok=True)
write_adapter(out, {
"lora": {"/".join(p): {"A": np.asarray(v["A"]), "B": np.asarray(v["B"])} for p, v in train["lora"].items()},
"rows": np.asarray(train["rows"]),
@@ -391,7 +397,7 @@ def build_main(args):
import jax.numpy as jnp
from ..agent import fetch
from .export import read_layers
- from .finetune import upload_archive
+ from .build import upload_archive
base_archive = fetch.fetch_weights(fetch.WHISTLE, force=True)
print(f" {'base':<9} {base_archive} {os.path.getsize(base_archive) / 1e6:.2f} MB")
diff --git a/needle/playground/server.py b/needle/playground/server.py
index fe5383a..9c43e75 100644
--- a/needle/playground/server.py
+++ b/needle/playground/server.py
@@ -66,7 +66,8 @@ def _finetune_worker(tools_json, api_key, samples, engine):
import types
try:
_FT.update(running=True, step="generating data", log=[], checkpoint=None, error=None)
- from ..model.finetune import generate_dataset, finetune_local, build_main, DEFAULT_BASE
+ from ..model.build import build_main
+ from ..model.finetune import generate_dataset, finetune_local, DEFAULT_BASE
tools = json.loads(tools_json)
rows = generate_dataset(
diff --git a/tests/test_build.py b/tests/test_build.py
index 32283b0..faf3ac6 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -12,7 +12,7 @@ def _build_args(checkpoint, out, lora=None, layers=None, platform=None):
def test_build_exports_loadable_cact(tiny_checkpoint, tmp_path, published_base):
- from needle.model.finetune import build_main
+ from needle.model.build import build_main
from needle.model.export import read_export
out = str(tmp_path / "tiny.cact")
@@ -63,7 +63,7 @@ def test_export_round_trips_a_projection(tiny_checkpoint, tmp_path):
def test_build_from_safetensors_checkpoint(tiny_checkpoint, tiny_checkpoint_safetensors, tmp_path, published_base):
- from needle.model.finetune import build_main
+ from needle.model.build import build_main
from needle.model.export import read_export
from needle.model.run import load_checkpoint
import numpy as np
@@ -81,7 +81,7 @@ def test_build_from_safetensors_checkpoint(tiny_checkpoint, tiny_checkpoint_safe
def test_build_layers_exports_the_rung(tiny_checkpoint, tmp_path, published_base):
- from needle.model.finetune import build_main
+ from needle.model.build import build_main
from needle.model.export import read_export
out = str(tmp_path / "rung.cact")
@@ -94,7 +94,7 @@ def test_build_layers_exports_the_rung(tiny_checkpoint, tmp_path, published_base
def test_build_platform_places_the_engine_and_the_archive_together(tiny_checkpoint, tmp_path, published_base, monkeypatch):
from needle.agent import fetch
- from needle.model.finetune import build_main
+ from needle.model.build import build_main
from needle.model.export import read_layers
def fake_platform(name, out_dir, generation=3, dest=None):
diff --git a/tests/test_fetch.py b/tests/test_fetch.py
index 1496ea0..fe6cb7c 100644
--- a/tests/test_fetch.py
+++ b/tests/test_fetch.py
@@ -331,3 +331,26 @@ def test_android_is_detected_from_the_api_level_or_the_runtime_env(monkeypatch):
monkeypatch.delenv("ANDROID_DATA")
monkeypatch.setattr(sys, "getandroidapilevel", lambda: 34, raising=False)
assert fetch._is_android() is True
+
+
+def test_building_the_published_archive_needs_no_training_stack(tmp_path, monkeypatch):
+ import needle._telemetry
+ from needle.agent import fetch
+ from needle.cli import main
+
+ base = tmp_path / "needle3.cact"
+ base.write_bytes(b"archive")
+
+ def fake_platform(name, out_dir, generation=3, dest=None):
+ (tmp_path / "pi").mkdir()
+ (tmp_path / "pi" / "needle").write_bytes(b"engine")
+ return [str(tmp_path / "pi" / "needle")]
+
+ monkeypatch.setattr(needle._telemetry, "track", lambda *a, **k: None)
+ monkeypatch.setattr(fetch, "fetch_weights", lambda generation=2, dest_dir=None, force=False: str(base))
+ monkeypatch.setattr(fetch, "download_platform", fake_platform)
+ for name in ("numpy", "jax"):
+ monkeypatch.setitem(sys.modules, name, None)
+ monkeypatch.setattr(sys, "argv", ["needle", "build", "--platform", "linux-arm64", "--out", str(tmp_path / "pi")])
+ main()
+ assert (tmp_path / "pi" / "needle3.cact").read_bytes() == b"archive"
diff --git a/tests/test_finetune.py b/tests/test_finetune.py
index 76fbf11..86c7f61 100644
--- a/tests/test_finetune.py
+++ b/tests/test_finetune.py
@@ -55,7 +55,8 @@ def test_finetune_writes_adapter(tiny_checkpoint, tmp_path):
def test_finetune_then_build_merges(tiny_checkpoint, tmp_path, published_base):
- from needle.model.finetune import finetune_local, build_main
+ from needle.model.build import build_main
+ from needle.model.finetune import finetune_local
from needle.model.export import read_export
data = tmp_path / "data.jsonl"
@@ -72,7 +73,8 @@ def test_finetune_then_build_merges(tiny_checkpoint, tmp_path, published_base):
def test_build_without_a_checkpoint_uses_the_adapter_base(tiny_checkpoint, tmp_path, published_base):
- from needle.model.finetune import finetune_local, build_main
+ from needle.model.build import build_main
+ from needle.model.finetune import finetune_local
from needle.model.export import read_export
data = tmp_path / "data.jsonl"
@@ -126,7 +128,8 @@ def test_finetune_adapter_records_realized_seed(tiny_checkpoint, tmp_path):
def test_finetune_adapter_defaults_to_safetensors_and_builds(tiny_checkpoint_safetensors, tmp_path, published_base):
- from needle.model.finetune import finetune_local, build_main
+ from needle.model.build import build_main
+ from needle.model.finetune import finetune_local
from needle.model.checkpoints import read_adapter
from needle.model.export import read_export
diff --git a/tests/test_whistle_finetune.py b/tests/test_whistle_finetune.py
index e319efe..cc76651 100644
--- a/tests/test_whistle_finetune.py
+++ b/tests/test_whistle_finetune.py
@@ -205,7 +205,7 @@ def test_tokens_come_from_a_file(tmp_path):
@pytest.mark.slow
def test_wrong_kinds_of_files_are_refused(tiny_whistle, tiny_checkpoint, published_whistle, tmp_path):
from needle.model.checkpoints import write_adapter
- from needle.model.finetune import build_main as needle_build
+ from needle.model.build import build_main as needle_build
from needle.model.whistle_finetune import build_main, load_base
with pytest.raises(SystemExit, match="not a Whistle checkpoint"):
@@ -230,6 +230,51 @@ def test_finetune_needs_an_epoch_and_a_batch():
finetune_main(types.SimpleNamespace(epochs=epochs, batch_size=batch))
+def _splits(tmp_path, **lines):
+ files = {}
+ for name in ("train", "validation", "test"):
+ (tmp_path / name).mkdir()
+ files[name] = _clips(tmp_path / name, lines.get(name, ["não é coração", "ação"]))
+ return files
+
+
+def _finetune(tiny_whistle, tmp_path, files, **kw):
+ from needle.model.whistle_finetune import finetune_main
+
+ finetune_main(types.SimpleNamespace(**{
+ **files, "language": "pt", "tokens": None, "checkpoint": tiny_whistle, "epochs": 1, "batch_size": 2,
+ "lr": 1e-3, "lora_rank": 4, "lora_alpha": 8.0, "seed": 0, "checkpoint_dir": str(tmp_path),
+ "out": str(tmp_path / "adapter.safetensors"), **kw}))
+
+
+def test_every_split_needs_clips_within_the_token_limit(tiny_whistle, tmp_path):
+ files = _splits(tmp_path, validation=["não é coração " * 30])
+ with pytest.raises(SystemExit, match="validation"):
+ _finetune(tiny_whistle, tmp_path, files)
+
+
+def test_a_new_language_needs_training_clips(tiny_whistle, tmp_path):
+ files = _splits(tmp_path)
+ rows = [json.loads(line) for line in open(files["test"], encoding="utf-8")]
+ with open(files["test"], "w", encoding="utf-8") as out:
+ out.writelines(json.dumps({**row, "language": "xx"}) + "\n" for row in rows)
+ with pytest.raises(SystemExit, match="xx"):
+ _finetune(tiny_whistle, tmp_path, files)
+
+
+def test_the_adapter_path_is_checked_before_training(tiny_whistle, tmp_path, capsys):
+ files = _splits(tmp_path)
+ with pytest.raises(SystemExit, match=r"\.safetensors"):
+ _finetune(tiny_whistle, tmp_path, files, out=str(tmp_path / "adapter.bin"))
+ assert "epoch" not in capsys.readouterr().out
+ out = tmp_path / "new" / "adapter.safetensors"
+ _finetune(tiny_whistle, tmp_path, files, out=str(out))
+ assert out.exists()
+
+
def test_cli_routes_finetune_and_build_and_takes_a_tuned_language(monkeypatch):
import sys
import needle._telemetry
diff --git a/tests/test_worker.py b/tests/test_worker.py
index 32cb3dc..f27d261 100644
--- a/tests/test_worker.py
+++ b/tests/test_worker.py
@@ -59,6 +59,15 @@ int needle_complete(const char* input, const float* pcm, int samples,
void needle_reset(void) {
resets++;
}
+
+int needle_embed(const char* input, const float* pcm, int samples,
+ float* output, int capacity) {
+ (void)input;
+ (void)pcm;
+ (void)samples;
+ for (int i = 0; output && i < capacity; i++) output[i] = (float)(model_id + i);
+ return 3;
+}
''')
if sys.platform == "darwin":
library = tmp_path / "libstub.dylib"
@@ -71,7 +80,7 @@ void needle_reset(void) {
def _weights(path, model_id):
- path.write_bytes((0x05E12A83).to_bytes(4, "little") +
+ path.write_bytes((0x05E12A84).to_bytes(4, "little") +
bytes([model_id, 1]))
return path
@@ -79,8 +88,8 @@ def _weights(path, model_id):
def test_finetunes_run_in_independent_processes(stub_engine, tmp_path):
first_path = _weights(tmp_path / "first.cact", 11)
second_path = _weights(tmp_path / "second.cact", 29)
- first = FineTuneWorker(stub_engine, first_path, "", "[]", None, 4096)
- second = FineTuneWorker(stub_engine, second_path, "", "[]", None, 4096)
+ first = FineTuneWorker(stub_engine, first_path, "", "[]", None, 4096, generation=3)
+ second = FineTuneWorker(stub_engine, second_path, "", "[]", None, 4096, generation=3)
try:
assert first.pid != second.pid
assert json.loads(first.complete("first", 8))["model"] == 11
@@ -122,4 +131,32 @@ def test_tuned_agents_use_independent_workers(stub_engine, tmp_path,
def test_worker_propagates_native_load_failure(stub_engine, tmp_path):
bad = _weights(tmp_path / "bad.cact", 0)
with pytest.raises(RuntimeError, match="needle_load failed"):
- FineTuneWorker(stub_engine, bad, "", "[]", None, 4096)
+ FineTuneWorker(stub_engine, bad, "", "[]", None, 4096, generation=3)
+
+
+def test_tuned_embeddings_go_through_the_worker(stub_engine, tmp_path):
+ worker = FineTuneWorker(stub_engine, _weights(tmp_path / "tuned.cact", 5), "", "[]", None, 4096,
+ generation=3)
+ try:
+ assert worker.embed("hello") == [5.0, 6.0, 7.0]
+ finally:
+ worker.close()
+
+
+def test_needle_2_takes_the_text_alone(monkeypatch):
+ import needle
+
+ class Engine:
+ def needle_init(self, system, tools, index):
+ return 0
+
+ def needle_complete(self, text, max_new_tokens, output, capacity):
+ output.value = b'{"type":"call","function_calls":[]}'
+ return 0
+
+ def needle_reset(self):
+ pass
+
+ monkeypatch.setattr(needle, "_lib", lambda generation=2: Engine())
+ monkeypatch.setattr(needle, "_active", {})
+ assert needle.Needle(tools="[]", generation=2).complete("hello")["function_calls"] == []