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.txtindex 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__.pyindex 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.pyindex 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_intlib.needle_reset.argtypes = []lib.needle_reset.restype = None@@ -96,8 +100,9 @@ def _child():breakoperation = 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():})continuetext = 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():})continueembedding = (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.pyindex 054436a..a68618b 100644--- a/needle/agent/tools.py+++ b/needle/agent/tools.py@@ -1,3 +1,5 @@+from __future__ import annotations+import enumimport inspectimport rediff --git a/needle/agent/whistle.py b/needle/agent/whistle.pyindex 4f7ec0f..00e474f 100644--- a/needle/agent/whistle.py+++ b/needle/agent/whistle.py@@ -103,7 +103,7 @@ def _read_wav(path):import numpyimport soxrexcept 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 Nonereturn soxr.resample(numpy.asarray(mono, numpy.float32), rate, SAMPLE_RATE, quality="HQ")diff --git a/needle/cli.py b/needle/cli.pyindex f91dddb..5958bcf 100644--- a/needle/cli.py+++ b/needle/cli.py@@ -339,7 +339,7 @@ def main():from .model.finetune import generate_maingenerate_main(args)elif args.command == "build":- from .model.finetune import build_main+ from .model.build import build_mainbuild_main(args)elif args.command == "download":import shutildiff --git a/needle/model/build.py b/needle/model/build.pynew file mode 100644index 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.pyindex a5d49f5..09fa437 100644--- a/needle/model/finetune.py+++ b/needle/model/finetune.py@@ -2,7 +2,7 @@ import concurrent.futuresimport jsonimport os-from .checkpoints import read_adapter, write_adapter+from .checkpoints import write_adapterimport sysimport urllib.requestfrom 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.pyindex 3e2a8bf..0ea7dd6 100644--- a/needle/model/whistle_finetune.py+++ b/needle/model/whistle_finetune.py@@ -6,7 +6,7 @@ from dataclasses import replaceimport numpy as np-from .checkpoints import read_adapter, write_adapter+from .checkpoints import is_safetensors, read_adapter, write_adapterfrom .finetune import _training_rng, init_lora, lora_target_paths, merge_lorafrom .whistle import LANGUAGES, Whistle, load_whistle@@ -101,7 +101,7 @@ def read_audio(path):import soxrexcept 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 Nonesamples = 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_BASEparams, 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 jnpfrom ..agent import fetchfrom .export import read_layers- from .finetune import upload_archive+ from .build import upload_archivebase_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.pyindex 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 typestry:_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_BASEtools = json.loads(tools_json)rows = generate_dataset(diff --git a/tests/test_build.py b/tests/test_build.pyindex 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_mainfrom needle.model.export import read_exportout = 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_mainfrom needle.model.export import read_exportfrom needle.model.run import load_checkpointimport numpy as np@@ -81,7 +81,7 @@ def test_build_from_safetensors_checkpoint(tiny_checkpoint, tiny_checkpoint_safedef 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_mainfrom needle.model.export import read_exportout = str(tmp_path / "rung.cact")@@ -94,7 +94,7 @@ def test_build_layers_exports_the_rung(tiny_checkpoint, tmp_path, published_basedef 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_mainfrom needle.model.export import read_layersdef fake_platform(name, out_dir, generation=3, dest=None):diff --git a/tests/test_fetch.py b/tests/test_fetch.pyindex 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.pyindex 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_localfrom needle.model.export import read_exportdata = 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_localfrom needle.model.export import read_exportdata = 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_localfrom needle.model.checkpoints import read_adapterfrom needle.model.export import read_exportdiff --git a/tests/test_whistle_finetune.py b/tests/test_whistle_finetune.pyindex 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.slowdef 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_buildfrom needle.model.whistle_finetune import build_main, load_basewith 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 sysimport needle._telemetrydiff --git a/tests/test_worker.py b/tests/test_worker.pyindex 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.pidassert 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"] == []