Crate needle_c 

C ABI shared library for Needle. Exposes a stable C interface for Python (ctypes/cffi), Go, Swift, etc.

API: needle_load(weights_path, vocab_path) → *NeedleHandle needle_load_bytes(weights_data, weights_len, vocab_data, vocab_len) → *NeedleHandle needle_run(handle, query, tools_json) → *char (free with needle_free_str) needle_run_stream(handle, query, tools_json, cb, ud) → *char (free with needle_free_str) needle_encode_contrastive(handle, text, out, dim) → bool needle_contrastive_dim(handle) → usize needle_retrieve_tools(handle, query, descs, n, k, idx, scores) → usize needle_free_str(s) needle_free(handle) needle_last_error() → *const char

Structs

NeedleHandle

Opaque handle to a loaded NeedleEngine.

Functions

needle_contrastive_dim^⚠

Return the contrastive embedding dimension (0 if no contrastive head loaded).

needle_encode_contrastive^⚠

Encode text into a L2-normalized contrastive embedding.

needle_free^⚠

Free a NeedleHandle returned by needle_load or needle_load_bytes. No-op on null.

needle_free_str^⚠

Free a string returned by needle_run or needle_run_stream. No-op on null.

needle_last_error

Return the last error message as a null-terminated C string, or null if none. The returned pointer is valid until the next call to any needle_* function on this thread. Do NOT free this pointer.

needle_load^⚠

Load a Needle model from disk. Returns null on failure. Caller must free with needle_free.

needle_load_bytes^⚠

Load a Needle model from in-memory byte buffers.

needle_retrieve_tools^⚠

Rank tool descriptions by contrastive similarity to a query.

needle_run^⚠

Run inference. Returns a heap-allocated JSON string. Caller must free with needle_free_str. Returns null on error.

needle_run_stream^⚠

Run inference with streaming. Returns the final post-processed output (same as needle_run).

Type Aliases

NeedleStreamCallback

C callback type for streaming: called once per generated token. token_id: raw token ID. piece: null-terminated UTF-8 text for this token (e.g., “ Paris“). user_data: caller-supplied context pointer.