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.
Whistle (#163)
Jakub Mrozbb665fc1e16a
diff --git a/llms.txt b/llms.txtindex 49c12d3..fea901d 100644--- a/llms.txt+++ b/llms.txt@@ -234,6 +234,9 @@ Adapt by swapping the Literal values for your own and keeping the shapes: closed- `needle run --checkpoint <base.safetensors> --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 [checkpoint] [--lora adapter] [--layers N] [--platform <folder>] [--out <path>]` - the fine-tuning pipeline; fine-tuning runs at the full 20 layers, `build` merges the adapter, slices the `--layers` rung (default 20), exports at 4 bits, and fetches the published `needle3.cact` on every run (without an adapter at full depth it ships that published 2-bit archive as is). `--platform` also downloads that platform's engine and header and makes `--out` a folder holding them plus `needle3.cact`.- `needle playground` - the browser UI locally (hosted at https://cactuscompute.com/needle).+- `needle whistle playground [clip.wav] [--language en] [--keywords "Siobhan, Krzysztof"] [--word-timestamps] [--weights whistle.cact]` - Whistle speech to text in the terminal: press Enter to speak, Enter again to stop, or pass a WAV file; `/language`, `/keywords`, `/timestamps` and `/file` change the settings between recordings. Needs the `[whistle]` extra. The Whistle engine and `whistle.cact` are fetched from `Cactus-Compute/whistle` on first use; `NEEDLE_WHISTLE_LIB_PATH` and `NEEDLE_WHISTLE_WEIGHTS` point at local ones.+- `needle whistle compare [clip.wav] [--weights whistle.cact]` - the same English speech through Whistle, Whisper tiny and base (openai-whisper) and Moonshine tiny v2 (moonshine-voice), one line per model with its weight size, time to first token, decode tokens per second, total time and transcript; `/file` runs a WAV between recordings. Whistle's timing comes from the engine's own JSON. Needs the `[whistle,whistle-compare]` extras.+- `needle whistle fetch [--platform-tag <tag>] [--out <dir>]` / `needle whistle download whistle | <platform> [--out <dir>]` - the Whistle counterparts of `needle fetch` and `needle download`: pre-download the Whistle engine library, the `whistle.cact` weights, or a platform folder with the `whistle` binary, `libwhistle.a` and `whistle.h`.- `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 `NEEDLE3_LIB_PATH` and `HF_HUB_OFFLINE` at https://cactuscompute.com/blog/needle-python-docs.- `needle platform finetune | generate | jobs | models | files | billing` - the hosted platform from the CLI (section above).- `needle download needle3 | needle3.safetensors | model-<id> | <org>/<repo>[/<file>.cact] | <platform> [--out <dir>]` - pull the base Needle 3 archive, a checkpoint to fine-tune, a platform-trained model by id (`--depth N` for one size), a published `.cact` (single-archive repos need only `<org>/<repo>`), or pass a platform folder name (`macos-arm64`, `linux-x86_64`, `wasm`, `wasm-component`, ...) to fetch that platform's engine files into `<out>/<platform>/`. Native runners are marked executable; `wasm-component` contains the WASI Preview 2 component and WIT contract.diff --git a/needle/__init__.py b/needle/__init__.pyindex fcf84b7..d1ea2c7 100644--- a/needle/__init__.py+++ b/needle/__init__.py@@ -11,9 +11,10 @@ import warningsfrom .agent.tools import Field, build_schema, pydantic_schema, tool, _is_pydantic_modelfrom ._telemetry import track as _trackfrom ._worker import FineTuneWorker+from .whistle import Whistle__version__ = "3.0.1"-__all__ = ["Needle", "ExtractionValidationError", "tool", "Field", "extract",+__all__ = ["Needle", "Whistle", "ExtractionValidationError", "tool", "Field", "extract","__version__"]@@ -80,8 +81,8 @@ def _confidence_head_present(path):def _library_path(generation=2):from .agent import fetch- generation = int(generation)- override = os.environ.get(f"NEEDLE{generation}_LIB_PATH")+ generation = fetch._engine(generation)+ override = os.environ.get(fetch.lib_path_env(generation))if generation == 2 and not override:# NEEDLE_LIB_PATH predates multi-generation dispatch and therefore# names the Needle 2 engine. Never route a v3 archive through it.@@ -89,9 +90,9 @@ def _library_path(generation=2):if override:return overridehere = os.path.dirname(os.path.abspath(__file__))- lib_name = fetch._lib_name()+ lib_name = fetch.lib_name(generation)stem, suffix = os.path.splitext(lib_name)- local_names = [f"{stem}{generation}{suffix}"]+ local_names = [lib_name if generation in fetch.NAMED_ENGINES else f"{stem}{generation}{suffix}"]if generation == 2:# Wheels published before the split shipped Needle 2 as libneedle.*.local_names.append(lib_name)@@ -100,9 +101,8 @@ def _library_path(generation=2):if os.path.exists(local):return localversion = fetch.engine_version(generation)- cache = os.path.join(os.path.expanduser("~"), ".cache", "cactus-needle",- f"v{generation}", version)- cached = os.path.join(cache, fetch._lib_name())+ cache = fetch.cache_dir(generation)+ cached = os.path.join(cache, lib_name)if os.path.exists(cached):return cachedos.makedirs(cache, exist_ok=True)diff --git a/needle/agent/fetch.py b/needle/agent/fetch.pyindex 5e03d54..44c79fa 100644--- a/needle/agent/fetch.py+++ b/needle/agent/fetch.py@@ -4,19 +4,34 @@ import sysconfigimport sysimport zipfile+WHISTLE = "whistle"+NEEDLE3_WHISTLE = "needle3_whistle"+ENGINE_REPOS = {2: "Cactus-Compute/needle2",3: "Cactus-Compute/needle3",+ NEEDLE3_WHISTLE: "Cactus-Compute/needle3",+ WHISTLE: "Cactus-Compute/whistle",}ENGINE_VERSIONS = {2: "2.0.4",3: "3.0.3",+ NEEDLE3_WHISTLE: "3.0.0",+ WHISTLE: "1.0.0",}BASE_WEIGHTS = {2: "needle2.cact",3: "needle3.cact",+ NEEDLE3_WHISTLE: "needle3.cact",+ WHISTLE: "whistle.cact",+}+# Engines named instead of numbered: one library per name, beside the generations.+LIB_PATH_ENVS = {+ NEEDLE3_WHISTLE: "NEEDLE3_WHISTLE_LIB_PATH",+ WHISTLE: "NEEDLE_WHISTLE_LIB_PATH",}+NAMED_ENGINES = tuple(LIB_PATH_ENVS)CHECKPOINT_PREFIX = "checkpoints"# Backwards-compatible aliases for callers that explicitly fetch Needle 2.@@ -50,6 +65,20 @@ def _lib_name():return "libneedle.so"+def _engine(generation):+ """The key of an engine in the tables above: a Needle generation, or a named engine."""+ return generation if generation in ENGINE_VERSIONS and not isinstance(generation, int) else int(generation)+++def lib_name(generation=2, tag=None):+ name = _lib_name_for(tag) if tag else _lib_name()+ return name.replace("needle", generation) if generation in NAMED_ENGINES else name+++def lib_path_env(generation=2):+ return LIB_PATH_ENVS.get(generation) or f"NEEDLE{generation}_LIB_PATH"++def _is_musl():"""True on a musl system (Alpine and friends).@@ -100,8 +129,9 @@ def other_libc_tag():return None-def engine_wheel(version, tag):- return "python/cactus_needle-{}-py3-none-{}.whl".format(version, tag)+def engine_wheel(version, tag, generation=2):+ name = generation if generation in NAMED_ENGINES else "needle"+ return "{}python/cactus_{}-{}-py3-none-{}.whl".format(repo_prefix(generation), name, version, tag)def unpublished_engine_wheels():@@ -113,27 +143,32 @@ def unpublished_engine_wheels():"""from huggingface_hub import list_repo_files- missing = []- for generation in sorted(ENGINE_VERSIONS):+ missing, listings = [], {}+ for generation in ENGINE_VERSIONS:repo = ENGINE_REPOS[generation]- present = set(list_repo_files(repo))+ if repo not in listings:+ # A repo that is private or not created yet holds none of its wheels.+ try:+ listings[repo] = set(list_repo_files(repo))+ except Exception:+ listings[repo] = set()for tag in WHEEL_TAGS:- wheel = engine_wheel(ENGINE_VERSIONS[generation], tag)- if wheel not in present:+ wheel = engine_wheel(ENGINE_VERSIONS[generation], tag, generation)+ if wheel not in listings[repo]:missing.append(repo + "/" + wheel)return missingdef engine_repo(generation=2):try:- return ENGINE_REPOS[int(generation)]+ return ENGINE_REPOS[_engine(generation)]except (KeyError, TypeError, ValueError) as exc:raise ValueError(f"unsupported Needle generation: {generation}") from excdef engine_version(generation=2):try:- return ENGINE_VERSIONS[int(generation)]+ return ENGINE_VERSIONS[_engine(generation)]except (KeyError, TypeError, ValueError) as exc:raise ValueError(f"unsupported Needle generation: {generation}") from exc@@ -155,7 +190,8 @@ def download_platform(name, out_dir, generation=2, dest=None):repo = engine_repo(generation)_register_download(generation)- files = [f for f in list_repo_files(repo) if f.startswith(name + "/")]+ prefix = repo_prefix(generation)+ files = [f for f in list_repo_files(repo) if f.startswith(prefix + name + "/")]if name not in PLATFORMS or not files:raise FileNotFoundError(f"{name} is not a published platform folder in {repo}")dest = dest or os.path.join(out_dir, name)@@ -165,7 +201,7 @@ def download_platform(name, out_dir, generation=2, dest=None):cached = hf_hub_download(repo_id=repo, filename=f, repo_type="model")target = os.path.join(dest, os.path.basename(f))shutil.copyfile(cached, target)- if os.path.basename(target) in ("needle", "needle.exe"):+ if os.path.splitext(os.path.basename(target))[0] in ("needle",) + NAMED_ENGINES:os.chmod(target, os.stat(target).st_mode | stat.S_IXUSR| stat.S_IXGRP | stat.S_IXOTH)out.append(target)@@ -174,14 +210,20 @@ def download_platform(name, out_dir, generation=2, dest=None):def base_weights(generation=2):try:- return BASE_WEIGHTS[int(generation)]+ return BASE_WEIGHTS[_engine(generation)]except (KeyError, TypeError, ValueError) as exc:raise ValueError(f"unsupported Needle generation: {generation}") from exc+def repo_prefix(generation=2):+ """Where an engine lives inside its repo. needle3_whistle shares needle3's."""+ return generation + "/" if generation == NEEDLE3_WHISTLE else ""++def cache_dir(generation=2):+ folder = generation if generation in NAMED_ENGINES else f"v{int(generation)}"return os.path.join(os.path.expanduser("~"), ".cache", "cactus-needle",- f"v{int(generation)}", engine_version(generation))+ folder, engine_version(generation))def fetch_weights(generation=2, dest_dir=None, force=False):@@ -240,10 +282,10 @@ def fetch_library(version=None, dest_dir=None, tag=None, generation=2):tag = tag or _platform_tag()repo = engine_repo(generation)_register_download(generation)- path = hf_hub_download(repo_id=repo, filename=engine_wheel(version, tag), repo_type="model")- lib = _lib_name_for(tag)+ path = hf_hub_download(repo_id=repo, filename=engine_wheel(version, tag, generation), repo_type="model")+ lib = lib_name(generation, tag)stem, suffix = os.path.splitext(lib)- member = f"{stem}{generation}{suffix}" if int(generation) >= 3 else lib+ member = lib if generation in NAMED_ENGINES or int(generation) < 3 else f"{stem}{generation}{suffix}"os.makedirs(dest_dir, exist_ok=True)with zipfile.ZipFile(path) as archive:data = archive.read("needle/" + member)diff --git a/needle/cli.py b/needle/cli.pyindex 7b12429..7ab4000 100644--- a/needle/cli.py+++ b/needle/cli.py@@ -14,6 +14,7 @@ HELP = """usage: needle <command> [options]download needle3 | needle3.safetensors | <platform> | model-<id> | <org>/<repo>[/<file>.cact]fetch fetch the engine library for this platformplayground serve the browser playground+ whistle speech to text: playground | compare | fetch | downloadneedle <command> --help for the options of one command.Check the readme for the rest."""@@ -39,6 +40,8 @@ def _download_target(spec):name = spec[:-5] if spec.endswith(".cact") else specif name in ("needle2", "needle3"):return "base", int(name[-1])+ if name == fetch.WHISTLE:+ return "base", nameif spec.endswith(".safetensors"):return "checkpoint", specraise SystemExit(@@ -262,6 +265,34 @@ def main():p.add_argument("--port", type=int, default=7860)p.add_argument("--host", type=str, default="127.0.0.1")+ from .whistle import LANGUAGES+ p = sub.add_parser("whistle")+ verbs = p.add_subparsers(dest="verb")+ v = verbs.add_parser("playground")+ v.add_argument("audio", type=str, nargs="?", default=None,+ help="A WAV file to transcribe once (default: press Enter to speak)")+ v.add_argument("--language", type=str, default=None, choices=LANGUAGES,+ help="Force the language (default: detect it)")+ v.add_argument("--keywords", type=str, default="",+ help="Words and phrases to favour, comma separated")+ v.add_argument("--word-timestamps", action="store_true",+ help="Show each word's start, end and probability")+ v.add_argument("--weights", type=str, default=None,+ help="whistle.cact to load (default: the published weights)")+ v = verbs.add_parser("compare")+ v.add_argument("audio", type=str, nargs="?", default=None,+ help="A WAV file to run through every model once (default: press Enter to speak)")+ v.add_argument("--weights", type=str, default=None,+ help="whistle.cact to load (default: the published weights)")+ v = verbs.add_parser("fetch")+ v.add_argument("--out", type=str, default=None,+ help="Directory to place the engine (default: the cache)")+ v.add_argument("--platform-tag", type=str, default=None,+ help="Fetch the build for another device, e.g. manylinux2014_aarch64")+ v = verbs.add_parser("download")+ v.add_argument("spec", type=str, help="whistle (the weights) or a platform folder (e.g. macos-arm64)")+ v.add_argument("--out", type=str, default=".", help="Directory to place the files")+args = parser.parse_args()if not args.command:@@ -272,6 +303,9 @@ def main():track("cli:" + args.command,{"generation": getattr(args, "generation", 2)})+ if args.command == "whistle" and args.verb in ("fetch", "download"):+ args.command, args.generation = args.verb, "whistle"+if args.command == "run":from .model.run import main as run_mainrun_main(args)@@ -292,20 +326,24 @@ def main():if kind == "platform":paths = fetch.download_platform(target, args.out,generation=args.generation)- if args.generation >= 3:+ if args.generation != 2:paths.append(fetch.fetch_weights(args.generation, os.path.join(args.out, target)))for path in paths:print(f" {'file':<9} {path} {os.path.getsize(path) / 1e6:.2f} MB")runner = next((p for p in paths- if os.path.basename(p) in ("needle", "needle.exe")), None)+ if os.path.basename(p) in ("needle", "needle.exe", "whistle", "whistle.exe")), None)if runner:- weights = f" --model {fetch.base_weights(args.generation)}" if args.generation >= 3 else ""- print(f" {'next':<9} {runner}{weights} --tools tools.json --serve")+ weights = f" --model {fetch.base_weights(args.generation)}" if args.generation != 2 else ""+ use = "--audio clip.wav" if args.generation == fetch.WHISTLE else "--tools tools.json --serve"+ print(f" {'next':<9} {runner}{weights} {use}")elif kind == "base":os.makedirs(args.out, exist_ok=True)path = fetch.fetch_weights(target, args.out)print(f" {'weights':<9} {path} {os.path.getsize(path) / 1e6:.2f} MB")- print(f" {'next':<9} needle.Needle(weights={path!r}, tools=[...])")+ if target == fetch.WHISTLE:+ print(f" {'next':<9} needle.Whistle(weights={path!r})")+ else:+ print(f" {'next':<9} needle.Needle(weights={path!r}, tools=[...])")elif kind == "hosted":from .platform import Platformfor path in Platform().download(target, args.out, depth=args.depth):@@ -336,17 +374,24 @@ def main():from .agent import fetchgeneration = args.generationversion = fetch.engine_version(generation)- dest = args.out or os.path.join(os.path.expanduser("~"), ".cache",- "cactus-needle", f"v{generation}", version)+ dest = args.out or fetch.cache_dir(generation)os.makedirs(dest, exist_ok=True)path = fetch.fetch_library(version, dest, tag=args.platform_tag,generation=generation)print(f" {'engine':<9} {path}")- print(f" {'deploy':<9} copy to ~/.cache/cactus-needle/v{generation}/{version}/ "- f"on the device, or point NEEDLE{generation}_LIB_PATH at the file")+ print(f" {'deploy':<9} copy to {fetch.cache_dir(generation)}/ "+ f"on the device, or point {fetch.lib_path_env(generation)} at the file")elif args.command == "platform":from .platform import main as platform_mainplatform_main(args)elif args.command == "playground":from .playground.server import main as playground_mainplayground_main(args)+ elif args.command == "whistle":+ if args.verb == "playground":+ from .whistle.playground import main as whistle_main+ elif args.verb == "compare":+ from .whistle.compare import main as whistle_main+ else:+ raise SystemExit("needle whistle playground | compare | fetch | download")+ whistle_main(args)diff --git a/needle/whistle/__init__.py b/needle/whistle/__init__.pynew file mode 100644index 0000000..bc4be7c--- /dev/null+++ b/needle/whistle/__init__.py@@ -0,0 +1,135 @@+from __future__ import annotations++import array+import ctypes+import json+import os+import sys+import wave++SAMPLE_RATE = 16000+LANGUAGES = ("en", "de", "fr", "es", "it", "nl", "pl")++_handle = None+_loaded = None+++def _weights_path():+ from .. import _base_weights_path+ from ..agent import fetch++ return os.environ.get("NEEDLE_WHISTLE_WEIGHTS") or _base_weights_path(fetch.WHISTLE)+++def _lib():+ global _handle+ if _handle is None:+ from .. import _load_cdll+ from ..agent import fetch++ lib = _load_cdll(fetch.WHISTLE)+ samples = ctypes.POINTER(ctypes.c_float)+ lib.whistle_load.argtypes = [ctypes.c_char_p, ctypes.c_uint64]+ lib.whistle_load.restype = ctypes.c_int+ lib.whistle_transcribe.argtypes = [samples, ctypes.c_int, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int,+ ctypes.c_char_p, ctypes.c_int]+ lib.whistle_transcribe.restype = ctypes.c_int+ lib.whistle_embed.argtypes = [samples, ctypes.c_int, samples, ctypes.c_int]+ lib.whistle_embed.restype = ctypes.c_int+ lib.whistle_last_error.argtypes = []+ lib.whistle_last_error.restype = ctypes.c_char_p+ _handle = lib+ return _handle+++def _read_wav(path):+ with wave.open(path, "rb") as source:+ channels, width, rate = source.getnchannels(), source.getsampwidth(), source.getframerate()+ raw = source.readframes(source.getnframes())+ if width == 3:+ values = [int.from_bytes(raw[i:i + 3], "little", signed=True) for i in range(0, len(raw), 3)]+ else:+ values = array.array({1: "B", 2: "h", 4: "i"}[width])+ values.frombytes(raw)+ if sys.byteorder == "big":+ values.byteswap()+ offset, scale = (128, 128.0) if width == 1 else (0, float(1 << (8 * width - 1)))+ scale *= channels+ mono = [(sum(frame) - offset * channels) / scale for frame in zip(*(values[c::channels] for c in range(channels)))]+ if rate == SAMPLE_RATE or not mono:+ return mono+ try:+ import numpy+ import soxr+ except ImportError:+ raise RuntimeError(f"resampling {rate} Hz audio to {SAMPLE_RATE} Hz needs soxr: pip install cactus-needle[whistle]") from None+ return soxr.resample(numpy.asarray(mono, numpy.float32), rate, SAMPLE_RATE, quality="HQ")+++def _samples(audio):+ if isinstance(audio, (str, os.PathLike)):+ audio = _read_wav(os.fspath(audio))+ data = array.array("f")+ if isinstance(audio, (bytes, bytearray)):+ data.frombytes(audio)+ elif isinstance(audio, array.array) and audio.typecode == "f":+ data = audio+ elif hasattr(audio, "tobytes") and getattr(audio, "dtype", None) is not None:+ data.frombytes(audio.astype("float32", copy=False).tobytes())+ else:+ data.extend(audio)+ return (ctypes.c_float * len(data)).from_buffer(data) if len(data) else (ctypes.c_float * 1)(), len(data)+++class Whistle:+ """Speech-to-text in English, German, French, Spanish, Italian, Dutch and Polish.++ Audio is a WAV file path or 16 kHz mono float samples in [-1, 1], at most 30 s.+ One model is loaded per process; it is not thread-safe.+ """++ def __init__(self, weights=None, buffer_size=1 << 18):+ self.weights = os.fspath(weights) if weights is not None else _weights_path()+ self._buffer = ctypes.create_string_buffer(buffer_size)+ self._bind()++ def _bind(self):+ global _loaded+ lib = _lib()+ if _loaded == self.weights:+ return lib+ with open(self.weights, "rb") as handle:+ data = handle.read()+ if lib.whistle_load(data, len(data)) < 0:+ _loaded = None+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))+ _loaded = self.weights+ return lib++ def transcribe(self, audio, language=None, keywords=None, word_timestamps=False) -> dict:+ """Returns {"text", "language", "ttft_ms", "decode_tps"}, plus "words" with start, end and probability when word_timestamps is set.++ language is one of LANGUAGES, or None to detect it. keywords are words or phrases for keyword biasing.+ """+ lib = self._bind()+ samples, count = _samples(audio)+ if keywords is not None and not isinstance(keywords, str):+ keywords = "\n".join(keywords)+ code = lib.whistle_transcribe(samples, count, language.encode("utf-8") if language else None,+ keywords.encode("utf-8") if keywords else None, int(bool(word_timestamps)),+ self._buffer, len(self._buffer))+ if code < 0:+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))+ return json.loads(self._buffer.value.decode("utf-8", "replace"))++ def embed(self, audio) -> list[float]:+ """The encoder output, one row of floats per 80 ms frame, flattened."""+ lib = self._bind()+ samples, count = _samples(audio)+ size = lib.whistle_embed(samples, count, None, 0)+ if size < 0:+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))+ output = (ctypes.c_float * size)()+ if lib.whistle_embed(samples, count, output, size) != size:+ raise RuntimeError(lib.whistle_last_error().decode("utf-8", "replace"))+ return list(output)diff --git a/needle/whistle/compare.py b/needle/whistle/compare.pynew file mode 100644index 0000000..c975260--- /dev/null+++ b/needle/whistle/compare.py@@ -0,0 +1,106 @@+import os+import time++from .playground import audio_path, prompt, record, status++HELP = """ Enter speak, Enter again to stop+ /file clip.wav run a file through every model+ /quit leave"""+INSTALL = 'pip install "cactus-needle[whistle,whistle-compare]"'+++def rate(marks):+ return (len(marks) - 1) / (marks[-1] - marks[0]) if len(marks) > 1 and marks[-1] > marks[0] else 0.0+++def load_whistle(weights):+ from . import Whistle++ whistle = Whistle(weights=weights)++ def transcribe(audio):+ result = whistle.transcribe(audio, language="en")+ return result["text"], result["ttft_ms"] / 1000, result["decode_tps"]++ return os.path.getsize(whistle.weights), transcribe+++def load_whisper(size):+ import whisper++ model = whisper.load_model(size, device="cpu")+ cache = os.path.join(os.getenv("XDG_CACHE_HOME", os.path.join(os.path.expanduser("~"), ".cache")), "whisper")+ marks = []+ model.decoder.register_forward_hook(lambda *_: marks.append(time.perf_counter()))++ def transcribe(audio):+ marks.clear()+ started = time.perf_counter()+ text = model.transcribe(audio, language="en", fp16=False)["text"].strip()+ return text, marks[0] - started, rate(marks)++ return os.path.getsize(os.path.join(cache, f"{size}.pt")), transcribe+++def load_moonshine():+ import moonshine_voice++ from . import SAMPLE_RATE++ path, arch = moonshine_voice.get_model_for_language("en", moonshine_voice.ModelArch.TINY_STREAMING)+ model = moonshine_voice.Transcriber(model_path=path, model_arch=arch)++ def transcribe(audio):+ lines = model.transcribe_without_streaming(audio.tolist(), SAMPLE_RATE).lines+ return " ".join(line.text.strip() for line in lines).strip(), None, None++ return sum(os.path.getsize(os.path.join(path, f)) for f in os.listdir(path)), transcribe+++def compare(models, audio):+ for name, size, transcribe in models:+ started = time.perf_counter()+ text, ttft, tokens = transcribe(audio)+ print(status(name, size, ttft, tokens, time.perf_counter() - started), " ", text or "(no speech)")+++def main(args):+ from . import SAMPLE_RATE, _read_wav++ try:+ import moonshine_voice # noqa: F401+ import numpy+ import whisper # noqa: F401+ except ImportError as error:+ raise SystemExit(f"{error.name} is not installed: {INSTALL}")+ print("whistle compare: downloading and initializing the models...", flush=True)+ models = [+ ("whistle", *load_whistle(args.weights)),+ ("whisper tiny", *load_whisper("tiny")),+ ("whisper base", *load_whisper("base")),+ ("moonshine tiny v2", *load_moonshine()),+ ]+ beat = numpy.arange(SAMPLE_RATE) * (numpy.pi / SAMPLE_RATE)+ warmup = (numpy.sin(440 * beat) * numpy.abs(numpy.sin(3 * beat))).astype(numpy.float32)+ for _, _, transcribe in models:+ transcribe(warmup)+ if args.audio:+ return compare(models, numpy.asarray(_read_wav(args.audio), numpy.float32))+ print(HELP)+ while True:+ line = prompt()+ command, _, rest = line.partition(" ")+ if command == "/quit":+ return+ if command == "/file":+ try:+ compare(models, numpy.asarray(_read_wav(audio_path(rest)), numpy.float32))+ except OSError as error:+ print(f" {error}")+ elif line == "":+ try:+ compare(models, numpy.asarray(record(), numpy.float32))+ except RuntimeError as error:+ print(f" {error}")+ else:+ print(HELP)diff --git a/needle/whistle/playground.py b/needle/whistle/playground.pynew file mode 100644index 0000000..ea283b4--- /dev/null+++ b/needle/whistle/playground.py@@ -0,0 +1,115 @@+import os+import time++HELP = """ Enter speak, Enter again to stop+ /language de force a language (en de fr es it nl pl), bare to detect it+ /keywords Siobhan, Krzysztof+ /timestamps toggle word times+ /file clip.wav transcribe a file+ /quit leave"""+CLEAR_ABOVE = "\x1b[1A\x1b[2K"+LIMIT_SECONDS = 30+++def audio_path(rest):+ """The path in a /file line, as a terminal hands it over: quoted, or with escaped spaces."""+ path = rest.strip()+ if len(path) > 1 and path[0] == path[-1] and path[0] in "'\"":+ return path[1:-1]+ return path.replace("\\ ", " ")+++def status(name, size, ttft, tokens, total):+ ttft = f"{ttft * 1000:.0f} ms" if ttft is not None else "-"+ tokens = f"{tokens:.0f} tok/s" if tokens is not None else "-"+ spent = f"{total:.1f} s" if total >= 10 else f"{total * 1000:.0f} ms"+ return f" {name:<18}{size / 1e6:>4.0f} MB ttft {ttft:>6} decode {tokens:>10} total {spent:>7}"+++def record():+ from . import SAMPLE_RATE++ try:+ import numpy+ import sounddevice+ import soxr+ except ImportError as error:+ raise RuntimeError(f'{error.name} is not installed: pip install "cactus-needle[whistle]"') from None+ chunks = []+ try:+ rate = int(sounddevice.query_devices(kind="input")["default_samplerate"])+ with sounddevice.InputStream(samplerate=rate, channels=1, dtype="float32", callback=lambda data, *_: chunks.append(data.copy())):+ print(CLEAR_ABOVE + "● recording, Enter to stop", end="", flush=True)+ try:+ input()+ except (EOFError, KeyboardInterrupt):+ print()+ except sounddevice.PortAudioError as error:+ raise RuntimeError(f"no microphone: {error}") from None+ print(CLEAR_ABOVE, end="", flush=True)+ heard = numpy.concatenate(chunks)[:, 0] if chunks else numpy.zeros(0, numpy.float32)+ audio = heard[:LIMIT_SECONDS * rate]+ if len(audio) < len(heard):+ print(f" keeping the first {LIMIT_SECONDS} s")+ return audio if rate == SAMPLE_RATE else soxr.resample(audio, rate, SAMPLE_RATE, quality="HQ")+++def prompt():+ try:+ return input("› ").strip()+ except (EOFError, KeyboardInterrupt):+ print()+ return "/quit"+++def transcribe(whistle, audio, state):+ started = time.perf_counter()+ try:+ result = whistle.transcribe(audio, language=state["language"], keywords=state["keywords"], word_timestamps=state["timestamps"])+ except (RuntimeError, OSError, EOFError) as error:+ print(f" {error}")+ return+ total = time.perf_counter() - started+ print(result["text"] or "(no speech)")+ for word in result.get("words", []):+ print(f" {word['start']:6.2f} - {word['end']:5.2f} {word['word']:<20} {word['probability']:.2f}")+ print(status("whistle", os.path.getsize(whistle.weights), result["ttft_ms"] / 1000, result["decode_tps"], total),+ " ", result["language"] or "no speech")+++def main(args):+ from . import LANGUAGES, Whistle++ state = {"language": args.language, "keywords": [k.strip() for k in args.keywords.split(",") if k.strip()], "timestamps": args.word_timestamps}+ print("whistle playground: downloading and initializing the model...", flush=True)+ whistle = Whistle(weights=args.weights)+ if args.audio:+ return transcribe(whistle, args.audio, state)+ print(HELP)+ while True:+ line = prompt()+ command, _, rest = line.partition(" ")+ if command == "/quit":+ return+ if command == "/language":+ language = rest.strip()+ if language and language not in LANGUAGES:+ print(" language is one of", " ".join(LANGUAGES))+ continue+ state["language"] = language or None+ print(" language", state["language"] or "detected")+ elif command in ("/keywords", "/keyword"):+ state["keywords"] = [k.strip() for k in rest.split(",") if k.strip()]+ print(" keywords", ", ".join(state["keywords"]) or "none")+ elif command == "/timestamps":+ state["timestamps"] = not state["timestamps"]+ print(" word timestamps", "on" if state["timestamps"] else "off")+ elif command == "/file":+ transcribe(whistle, audio_path(rest), state)+ elif line == "":+ try:+ transcribe(whistle, record(), state)+ except RuntimeError as error:+ print(f" {error}")+ else:+ print(HELP)diff --git a/pyproject.toml b/pyproject.tomlindex a6cefce..3cee9c7 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -25,6 +25,8 @@ metal = ["jaxlib==0.4.38","jax-metal"]+whistle = ["numpy", "soxr", "sounddevice"]+whistle-compare = ["openai-whisper", "moonshine-voice"]test = ["pytest", "pydantic"][project.scripts]diff --git a/setup b/setupindex 3b0b0af..61c8446 100755--- a/setup+++ b/setup@@ -31,7 +31,7 @@ source "$VENV_DIR/bin/activate"if [ "$UV_INSTALL" = "pip install" ]; thenpip install --upgrade pip -qfi-$UV_INSTALL -e ".[train]" -q+$UV_INSTALL -e ".[train,whistle]" -qif command -v nvidia-smi >/dev/null 2>&1 && nvidia-smi >/dev/null 2>&1; thenecho "NVIDIA GPU detected; installing gpu extras..."diff --git a/setup.bat b/setup.batindex 788ca6d..c63f598 100644--- a/setup.bat+++ b/setup.bat@@ -19,6 +19,6 @@ if not exist "%VENV_DIR%\Scripts\python.exe" %PYTHON_CMD% -m venv "%VENV_DIR%"call "%VENV_DIR%\Scripts\activate.bat"python -m pip install --upgrade pip -q-python -m pip install -e ".[train]" -q+python -m pip install -e ".[train,whistle]" -qneedle --helpdiff --git a/tests/conftest.py b/tests/conftest.pyindex da63a86..8d8bfad 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -13,24 +13,22 @@ def _engine_available(generation=3):import needlefrom needle.agent import fetch- override = os.environ.get(f"NEEDLE{generation}_LIB_PATH")+ override = os.environ.get(fetch.lib_path_env(generation))if generation == 2 and not override:override = os.environ.get("NEEDLE_LIB_PATH")if override:return os.path.exists(override)here = os.path.dirname(needle.__file__)- name = fetch._lib_name()+ name = fetch.lib_name(generation)stem, suffix = os.path.splitext(name)- local_names = [f"{stem}{generation}{suffix}"]+ local_names = [name if generation == fetch.WHISTLE else f"{stem}{generation}{suffix}"]if generation == 2:local_names.append(name)if any(os.path.exists(os.path.join(here, local)) for local in local_names):return True- cache = os.path.join(os.path.expanduser("~"), ".cache", "cactus-needle",- f"v{generation}", fetch.engine_version(generation), name)- return os.path.exists(cache)+ return os.path.exists(os.path.join(fetch.cache_dir(generation), name))except Exception:return Falsediff --git a/tests/test_fetch.py b/tests/test_fetch.pyindex 5e59cca..0d76862 100644--- a/tests/test_fetch.py+++ b/tests/test_fetch.py@@ -108,11 +108,11 @@ def test_component_platform_is_downloadable():def test_unpublished_engine_wheels_lists_every_missing_tag(monkeypatch):from needle.agent import fetch- published = {- repo: {fetch.engine_wheel(version, tag) for tag in fetch.WHEEL_TAGS}- for repo, version in ((fetch.ENGINE_REPOS[2], fetch.ENGINE_VERSIONS[2]),- (fetch.ENGINE_REPOS[3], fetch.ENGINE_VERSIONS[3]))- }+ published = {}+ for generation, version in fetch.ENGINE_VERSIONS.items():+ # needle3 hosts both its own engine and needle3_whistle, so the sets merge.+ published.setdefault(fetch.ENGINE_REPOS[generation], set()).update(+ fetch.engine_wheel(version, tag, generation) for tag in fetch.WHEEL_TAGS)monkeypatch.setattr("huggingface_hub.list_repo_files",lambda repo: sorted(published[repo]) + ["needle3.cact"])assert fetch.unpublished_engine_wheels() == []@@ -122,6 +122,29 @@ def test_unpublished_engine_wheels_lists_every_missing_tag(monkeypatch):published[repo3].remove(dropped)assert fetch.unpublished_engine_wheels() == [repo3 + "/" + dropped]+ audio = fetch.engine_wheel(fetch.ENGINE_VERSIONS[fetch.NEEDLE3_WHISTLE], "win_arm64", fetch.NEEDLE3_WHISTLE)+ published[repo3].remove(audio)+ assert fetch.unpublished_engine_wheels() == [repo3 + "/" + dropped, repo3 + "/" + audio]+ published[repo3].add(audio)++ whistle = fetch.ENGINE_REPOS[fetch.WHISTLE]+ published[whistle].clear()+ missing = fetch.unpublished_engine_wheels()+ assert len(missing) == 1 + len(fetch.WHEEL_TAGS)+ assert missing[-1] == f"{whistle}/python/cactus_whistle-{fetch.ENGINE_VERSIONS[fetch.WHISTLE]}-py3-none-win_arm64.whl"+++def test_a_repo_that_cannot_be_listed_holds_none_of_its_wheels(monkeypatch):+ """The whistle repo is private until release; the gate must report, not raise."""+ from needle.agent import fetch++ def refuse(repo):+ raise OSError("401 private repo")++ monkeypatch.setattr("huggingface_hub.list_repo_files", refuse)+ missing = fetch.unpublished_engine_wheels()+ assert len(missing) == len(fetch.ENGINE_VERSIONS) * len(fetch.WHEEL_TAGS)+def test_release_gate_runs_before_the_publish_step():from pathlib import Pathdiff --git a/tests/test_whistle.py b/tests/test_whistle.pynew file mode 100644index 0000000..d98e625--- /dev/null+++ b/tests/test_whistle.py@@ -0,0 +1,382 @@+import array+import math+import os+import struct+import sys+import wave++import pytest++from conftest import _engine_available+++def _whistle_weights():+ from needle.agent import fetch++ return os.environ.get("NEEDLE_WHISTLE_WEIGHTS") or os.path.join(fetch.cache_dir(fetch.WHISTLE), fetch.base_weights(fetch.WHISTLE))+++requires_whistle = pytest.mark.skipif(not (_engine_available("whistle") and os.path.exists(_whistle_weights())),+ reason="Whistle engine or whistle.cact not installed (auto-fetched from HF on first real use)")+++def test_engine_and_weights_resolve_like_needle(tmp_path, monkeypatch):+ import zipfile+ import needle+ from needle import whistle+ from needle.agent import fetch++ monkeypatch.setattr(os.path, "expanduser", lambda path: str(tmp_path))+ monkeypatch.setattr(needle, "__file__", str(tmp_path / "package" / "__init__.py"))+ monkeypatch.setattr(fetch, "_register_download", lambda generation: None)+ monkeypatch.delenv("NEEDLE_WHISTLE_WEIGHTS", raising=False)+ monkeypatch.setenv("NEEDLE_WHISTLE_LIB_PATH", "/opt/libwhistle.so")+ assert needle._library_path(fetch.WHISTLE) == "/opt/libwhistle.so"+ monkeypatch.delenv("NEEDLE_WHISTLE_LIB_PATH")++ lib = fetch.lib_name(fetch.WHISTLE)+ wheel, weights, fetched = tmp_path / "engine.whl", tmp_path / "published.cact", []+ with zipfile.ZipFile(wheel, "w") as archive:+ archive.writestr("needle/" + lib, b"engine")+ weights.write_bytes(b"weights")+ monkeypatch.setattr("huggingface_hub.hf_hub_download",+ lambda **kwargs: fetched.append((kwargs["repo_id"], kwargs["filename"])) or str(weights if kwargs["filename"].endswith(".cact") else wheel))+ cache = tmp_path / ".cache" / "cactus-needle" / "whistle" / fetch.ENGINE_VERSIONS[fetch.WHISTLE]+ assert lib.startswith("libwhistle.") and needle._library_path(fetch.WHISTLE) == str(cache / lib) and (cache / lib).read_bytes() == b"engine"+ assert whistle._weights_path() == str(cache / "whistle.cact") and (cache / "whistle.cact").read_bytes() == b"weights"+ assert fetched == [("Cactus-Compute/whistle", f"python/cactus_whistle-{fetch.ENGINE_VERSIONS[fetch.WHISTLE]}-py3-none-{fetch._platform_tag()}.whl"),+ ("Cactus-Compute/whistle", "whistle.cact")]+ assert needle._library_path(fetch.WHISTLE) and whistle._weights_path() and len(fetched) == 2+ monkeypatch.setenv("NEEDLE_WHISTLE_WEIGHTS", "/opt/whistle.cact")+ assert whistle._weights_path() == "/opt/whistle.cact"+++def test_cli_fetches_the_whistle_engine_and_weights(tmp_path, monkeypatch, capsys):+ import sys+ import needle._telemetry+ import needle.cli+ from needle.agent import fetch++ calls = []+ monkeypatch.setattr(needle._telemetry, "track", lambda *a, **k: None)+ monkeypatch.setattr(fetch, "fetch_library", lambda version, dest, tag=None, generation=2: calls.append((version, tag, generation)) or os.path.join(dest, "libwhistle.so"))+ monkeypatch.setattr(fetch, "fetch_weights", lambda generation, dest: calls.append((generation, dest)) or __file__)+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "fetch", "--out", str(tmp_path), "--platform-tag", "manylinux2014_aarch64"])+ needle.cli.main()+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "download", "whistle", "--out", str(tmp_path)])+ needle.cli.main()+ assert calls == [(fetch.ENGINE_VERSIONS[fetch.WHISTLE], "manylinux2014_aarch64", fetch.WHISTLE), (fetch.WHISTLE, str(tmp_path))]+ out = capsys.readouterr().out+ assert "NEEDLE_WHISTLE_LIB_PATH" in out and "needle.Whistle(weights=" in out+++def _tone(seconds, rate=16000):+ return [0.3 * math.sin(2 * math.pi * 220 * i / rate) for i in range(int(seconds * rate))]+++def _write_wav(path, samples, rate, channels=1, width=2):+ peak = (1 << (8 * width - 1)) - 1+ with wave.open(str(path), "wb") as out:+ out.setnchannels(channels)+ out.setsampwidth(width)+ out.setframerate(rate)+ for value in samples:+ level = int(value * peak)+ frame = bytes([level + 128]) if width == 1 else level.to_bytes(width, "little", signed=True)+ out.writeframes(frame * channels)++[email protected]("rate,channels,width", [(16000, 1, 2), (8000, 1, 2), (44100, 2, 2), (16000, 1, 1), (22050, 2, 3), (48000, 1, 4)])+def test_wav_files_become_16k_mono_floats(tmp_path, rate, channels, width):+ from needle.whistle import _read_wav++ if rate != 16000:+ pytest.importorskip("soxr")+ path = tmp_path / "tone.wav"+ _write_wav(path, _tone(0.5, rate), rate, channels, width)+ samples = _read_wav(str(path))+ assert abs(len(samples) - 8000) <= 1+ assert 0.28 < max(samples) < 0.31 and -0.31 < min(samples) < -0.28+ crossings = sum(1 for a, b in zip(samples, samples[1:]) if a < 0 <= b)+ assert 108 <= crossings <= 111+++def test_samples_accept_lists_arrays_and_float32_bytes():+ from needle.whistle import _samples++ values = [0.0, 0.5, -0.25]+ inputs = [values, array.array("f", values), struct.pack("<3f", *values), (v for v in values)]+ numpy = pytest.importorskip("numpy")+ inputs.append(numpy.array(values, numpy.float64))+ for audio in inputs:+ buffer, count = _samples(audio)+ assert count == 3 and list(buffer) == values+ assert _samples([])[1] == 0+++@requires_whistle+def test_silence_is_an_empty_transcript():+ from needle import Whistle++ result = Whistle().transcribe([0.0] * 16000, word_timestamps=True)+ assert result == {"text": "", "language": "", "words": [], "ttft_ms": 0.0, "decode_tps": 0.0}+++@requires_whistle+def test_transcribe_returns_text_language_and_timed_words(tmp_path):+ from needle import Whistle+ from needle.whistle import LANGUAGES++ whistle = Whistle()+ sound = [v * (0.2 + 0.8 * abs(math.sin(math.pi * 3 * i / 16000))) for i, v in enumerate(_tone(3))]+ plain = whistle.transcribe(sound)+ assert set(plain) == {"text", "language", "ttft_ms", "decode_tps"} and plain["language"] in LANGUAGES + ("",)+ assert (plain["ttft_ms"] > 0) == bool(plain["language"]) and plain["decode_tps"] >= 0+ path = tmp_path / "sound.wav"+ _write_wav(path, sound, 16000)+ timed = whistle.transcribe(path, language="en", keywords=["Siobhan", "Krzysztof"], word_timestamps=True)+ assert timed["language"] == "en" and isinstance(timed["text"], str)+ starts = [word["start"] for word in timed["words"]]+ assert starts == sorted(starts)+ assert all(0 <= word["start"] <= word["end"] <= 3.01 and 0 <= word["probability"] <= 1 for word in timed["words"])+++@requires_whistle+def test_embed_and_the_30_second_limit():+ from needle import Whistle++ whistle = Whistle()+ embedding = whistle.embed(_tone(1))+ assert len(embedding) > 0 and all(isinstance(v, float) for v in embedding[:8])+ with pytest.raises(RuntimeError, match="30 s"):+ whistle.transcribe([0.0] * (30 * 16000 + 1))+++@requires_whistle+def test_missing_weights_fail_clearly(tmp_path):+ from needle import Whistle++ broken = tmp_path / "broken.cact"+ broken.write_bytes(b"not a model at all")+ with pytest.raises(RuntimeError):+ Whistle(weights=broken)+ whistle = Whistle()+ assert os.path.getsize(whistle.weights) > 0 and whistle.transcribe([0.0] * 16000)["text"] == ""+++class _Whistle:+ weights = __file__++ def __init__(self, result):+ self.result = result+ self.calls = []++ def transcribe(self, audio, **options):+ self.calls.append((audio, options))+ return self.result+++class _Microphone:+ PortAudioError = OSError++ def __init__(self, rate, seconds):+ self.rate, self.seconds, self.opened = rate, seconds, None++ def query_devices(self, kind):+ return {"default_samplerate": float(self.rate)}++ def InputStream(self, **options):+ import numpy++ microphone = self++ class Stream:+ def __enter__(self):+ microphone.opened = options+ options["callback"](numpy.full((microphone.rate * microphone.seconds, 1), 0.25, numpy.float32), None, None, None)++ def __exit__(self, *_):+ return False++ return Stream()+++def test_record_resamples_the_microphone_to_16_khz_and_keeps_30_s(monkeypatch, capsys):+ numpy = pytest.importorskip("numpy")+ pytest.importorskip("soxr")+ from needle.whistle.playground import record++ microphone = _Microphone(48000, 1)+ monkeypatch.setitem(sys.modules, "sounddevice", microphone)+ monkeypatch.setattr("builtins.input", lambda *_: "")+ audio = record()+ assert microphone.opened["samplerate"] == 48000 and microphone.opened["channels"] == 1+ assert audio.dtype == numpy.float32 and len(audio) == 16000 and abs(float(audio[8000]) - 0.25) < 0.01+ assert "recording, Enter to stop" in capsys.readouterr().out+ monkeypatch.setitem(sys.modules, "sounddevice", _Microphone(16000, 31))+ assert len(record()) == 30 * 16000+ assert "keeping the first 30 s" in capsys.readouterr().out+++def test_record_says_what_is_missing(monkeypatch):+ from needle.whistle.playground import record++ monkeypatch.setitem(sys.modules, "sounddevice", None)+ with pytest.raises(RuntimeError, match=r"cactus-needle\[whistle\]"):+ record()+++def test_rate_counts_steps_after_the_first_mark():+ from needle.whistle.compare import rate++ assert rate([1.0, 1.5, 2.0]) == 2.0+ assert rate([1.0]) == 0.0 and rate([]) == 0.0 and rate([2.0, 2.0]) == 0.0+++def test_compare_prints_one_line_per_model_with_dashes_for_missing_timing(capsys):+ from needle.whistle.compare import compare++ models = [("whistle", 17e6, lambda audio: ("hello there", 0.013, 1264.0)),+ ("moonshine tiny v2", 45e6, lambda audio: ("", None, None))]+ compare(models, [0.0] * 16000)+ lines = capsys.readouterr().out.splitlines()+ assert len(lines) == 2+ assert lines[0].startswith(" whistle 17 MB ttft 13 ms decode 1264 tok/s total")+ assert lines[0].endswith("ms hello there")+ assert lines[1].startswith(" moonshine tiny v2 45 MB ttft - decode - total")+ assert lines[1].endswith("ms (no speech)")+++def test_playground_and_compare_share_one_status_line():+ from needle.whistle.playground import status++ assert status("whistle", 17e6, 0.0137, 1264.4, 0.048) == " whistle 17 MB ttft 14 ms decode 1264 tok/s total 48 ms"+ assert status("moonshine tiny v2", 145e6, None, None, 0.21) == " moonshine tiny v2 145 MB ttft - decode - total 210 ms"+++def test_status_reads_a_slow_run_in_seconds():+ from needle.whistle.playground import status++ assert status("whistle", 17e6, 0.0137, 1264.4, 12.5).endswith("total 12.5 s")+ assert status("whistle", 17e6, 0.0137, 1264.4, 9.9).endswith("total 9900 ms")+++def test_audio_path_takes_a_path_as_a_terminal_hands_it_over():+ from needle.whistle.playground import audio_path++ assert audio_path(" clip.wav ") == "clip.wav"+ assert audio_path('"my clips/a b.wav"') == "my clips/a b.wav"+ assert audio_path("'my clips/a b.wav'") == "my clips/a b.wav"+ assert audio_path("my\\ clips/a\\ b.wav") == "my clips/a b.wav"+++def test_playground_prints_text_words_and_timing(capsys):+ from needle.whistle.playground import transcribe++ whistle = _Whistle({"text": "hello there", "language": "en", "ttft_ms": 12.6, "decode_tps": 900.4,+ "words": [{"word": "hello", "start": 0.1, "end": 0.4, "probability": 0.98}]})+ transcribe(whistle, "clip.wav", {"language": "en", "keywords": ["Siobhan"], "timestamps": True})+ out = capsys.readouterr().out.splitlines()+ assert whistle.calls == [("clip.wav", {"language": "en", "keywords": ["Siobhan"], "word_timestamps": True})]+ assert out[0] == "hello there"+ assert out[1].split() == ["0.10", "-", "0.40", "hello", "0.98"]+ assert out[2].startswith(" whistle ") and "ttft 13 ms decode 900 tok/s total" in out[2] and out[2].endswith("ms en")+++def test_playground_reports_engine_errors_instead_of_raising(capsys):+ from needle.whistle.playground import transcribe++ class Broken:+ def transcribe(self, audio, **options):+ raise RuntimeError("audio limit is 30 s")++ transcribe(Broken(), "long.wav", {"language": None, "keywords": [], "timestamps": False})+ assert capsys.readouterr().out == " audio limit is 30 s\n"+++def test_playground_keeps_the_language_when_the_code_is_not_one_of_ours(monkeypatch, capsys):+ from needle.whistle import playground++ lines = iter(["/language de", "/language EN", "/language", "/quit"])+ monkeypatch.setattr(playground, "prompt", lambda: next(lines))+ monkeypatch.setattr("needle.whistle.Whistle", lambda weights=None: _Whistle({}))+ playground.main(type("Args", (), {"audio": None, "language": None, "keywords": "",+ "word_timestamps": False, "weights": None})())+ out = capsys.readouterr().out+ assert "language de" in out and "language is one of en de fr es it nl pl" in out and "language detected" in out+++def test_compare_runs_a_file_the_same_way_the_playground_does(monkeypatch, capsys):+ pytest.importorskip("numpy")+ from needle.whistle import compare as whistle_compare++ seen, read = [], []+ monkeypatch.setattr(whistle_compare, "compare", lambda models, audio: seen.append(len(audio)))+ monkeypatch.setattr("needle.whistle._read_wav", lambda path: read.append(path) or [0.0] * 16000)+ lines = iter(['/file "my clips/a b.wav"', "/quit"])+ monkeypatch.setattr(whistle_compare, "prompt", lambda: next(lines))+ monkeypatch.setattr(whistle_compare, "load_whistle", lambda weights: (17e6, lambda audio: ("", None, None)))+ monkeypatch.setattr(whistle_compare, "load_whisper", lambda size: (76e6, lambda audio: ("", None, None)))+ monkeypatch.setattr(whistle_compare, "load_moonshine", lambda: (45e6, lambda audio: ("", None, None)))+ whistle_compare.main(type("Args", (), {"audio": None, "weights": None})())+ assert read == ["my clips/a b.wav"] and seen == [16000]+++def test_compare_needs_its_extra(monkeypatch):+ from needle.whistle import compare as whistle_compare++ monkeypatch.setitem(sys.modules, "whisper", None)+ with pytest.raises(SystemExit, match=r"cactus-needle\[whistle,whistle-compare\]"):+ whistle_compare.main(type("Args", (), {"audio": None, "weights": None})())+++def test_cli_routes_the_whistle_commands(monkeypatch):+ import needle._telemetry+ import needle.cli+ import needle.whistle.playground+ import needle.whistle.compare++ seen = []+ monkeypatch.setattr(needle._telemetry, "track", lambda *a, **k: None)+ monkeypatch.setattr(needle.whistle.playground, "main", lambda args: seen.append(("playground", args)))+ monkeypatch.setattr(needle.whistle.compare, "main", lambda args: seen.append(("compare", args)))+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "playground", "clip.wav", "--language", "de", "--keywords", "Siobhan, Krzysztof", "--word-timestamps"])+ needle.cli.main()+ monkeypatch.setattr(sys, "argv", ["needle", "whistle", "compare", "--weights", "w.cact"])+ needle.cli.main()+ assert [s[0] for s in seen] == ["playground", "compare"]+ assert (seen[0][1].audio, seen[0][1].language, seen[0][1].keywords, seen[0][1].word_timestamps) == ("clip.wav", "de", "Siobhan, Krzysztof", True)+ assert (seen[1][1].audio, seen[1][1].weights) == (None, "w.cact")+ monkeypatch.setattr(sys, "argv", ["needle", "whistle"])+ with pytest.raises(SystemExit, match="needle whistle playground \\| compare \\| fetch \\| download"):+ needle.cli.main()+++def test_needle3_whistle_resolves_inside_the_needle3_repo(tmp_path, monkeypatch):+ """The combined engine shares needle3's repo, so every path it fetches is prefixed."""+ import zipfile+ import needle+ from needle.agent import fetch++ audio = fetch.NEEDLE3_WHISTLE+ assert fetch.engine_repo(audio) == fetch.engine_repo(3)+ assert fetch.engine_version(audio) == "3.0.0"+ assert fetch.lib_name(audio) == fetch.lib_name(3).replace("needle", audio)+ assert fetch.engine_wheel("3.0.0", "win_arm64", audio).startswith(audio + "/python/")+ assert fetch.engine_wheel("3.0.3", "win_arm64", 3).startswith("python/")++ monkeypatch.setattr(os.path, "expanduser", lambda path: str(tmp_path))+ monkeypatch.setattr(needle, "__file__", str(tmp_path / "package" / "__init__.py"))+ monkeypatch.setattr(fetch, "_register_download", lambda generation: None)+ monkeypatch.setenv(fetch.lib_path_env(audio), "/opt/libneedle3_whistle.so")+ assert needle._library_path(audio) == "/opt/libneedle3_whistle.so"+ monkeypatch.delenv(fetch.lib_path_env(audio))++ wheel, fetched = tmp_path / "engine.whl", []+ with zipfile.ZipFile(wheel, "w") as archive:+ archive.writestr("needle/" + fetch.lib_name(audio), b"engine")+ monkeypatch.setattr("huggingface_hub.hf_hub_download",+ lambda **kwargs: fetched.append(kwargs["filename"]) or str(wheel))+ resolved = needle._library_path(audio)+ assert resolved == str(tmp_path / ".cache" / "cactus-needle" / audio / "3.0.0" / fetch.lib_name(audio))+ assert fetched == [fetch.engine_wheel("3.0.0", fetch._platform_tag(), audio)]