Module needle 

Raw declarations for the Needle 3 engine C API (include/needle.h).

Overview

Nine functions, no handles, no opaque types. The engine owns one process-global model per kind: a text model (NEEDLE_TEXT, Needle 3) and a speech model (NEEDLE_SPEECH, Whistle). needle_load reads whichever kind an archive holds and keeps the other, so both can live in one process; needle_models reports which are loaded.

The text model is configured with needle_init, answers with needle_complete and is rewound by needle_reset. The speech model transcribes with needle_transcribe, and also runs inside needle_complete when it is handed a clip instead of a string, configured by needle_set_audio. needle_embed embeds either kind of input.

The declarations are written by hand rather than generated. Nine stable entry points do not justify a bindgen build dependency, and hand-written signatures let every function carry the # Safety contract that was measured against the shipped archive.

Every function that can fail returns a negative value when it does, and needle_last_error then names the reason. That string is one process-global slot shared by both kinds, owned by the runtime and overwritten by the next call: copy it before calling anything else.

Audio is 16 kHz mono f32 PCM in [-1, 1], at most 30 seconds (480 000 samples) per call.

Usage

use core::ffi::{c_char, c_int, c_ulonglong};

use cactus_sys::{NEEDLE_TEXT, needle_complete, needle_init, needle_load, needle_models};

let weights: &[u8] = b"...contents of needle3.cact...";
let mut out = [0u8; 64 * 1024];

// SAFETY: every call below happens on one thread, in order, and the engine copies the
// archive during `needle_load`, so `weights` needs no particular lifetime afterwards.
unsafe {
    assert_eq!(needle_load(weights.as_ptr(), weights.len() as c_ulonglong), 0);
    assert_ne!(needle_models() & NEEDLE_TEXT, 0);
    assert!(needle_init(c"You are terse.".as_ptr(), c"[]".as_ptr(), core::ptr::null()) > 0);

    let tokens = needle_complete(
        c"hello".as_ptr(),
        core::ptr::null(),
        0,
        64,
        out.as_mut_ptr().cast::<c_char>(),
        out.len() as c_int,
    );
    assert!(tokens >= 0);
}

Constants

NEEDLE_ENGINE_COMMIT

Commit of the Cactus-Compute/needle3 Hugging Face repository this crate is pinned to.

NEEDLE_SPEECH

Bit set in needle_models when a speech model (Whistle) is loaded.

NEEDLE_TEXT

Bit set in needle_models when a text model (Needle 3) is loaded.

Functions

needle_complete^⚠

Runs one completion on text or on a speech clip and writes a JSON envelope into out.

needle_embed^⚠

Embeds text or a speech clip, or reports how many floats that takes.

needle_init^⚠

Configures the conversation prefix: system prompt, tool declarations and tool index.

needle_last_error^⚠

Returns the reason the last failing call failed.

needle_load^⚠

Loads a .cact weight archive from memory.

needle_models^⚠

Reports which kinds of model this process has loaded.

needle_reset^⚠

Rewinds the conversation to the prefix that needle_init built.

needle_set_audio^⚠

Configures the transcription that needle_complete runs for itself on a clip.

needle_transcribe^⚠

Transcribes one speech clip and writes a JSON envelope into out.