cactus-sys 0.2.0

Raw FFI bindings to Cactus Compute inference engines (Needle 3, Whistle)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

#ifndef NEEDLE_H
#define NEEDLE_H

#ifndef NEEDLE_API
#define NEEDLE_API __attribute__((visibility("default")))
#endif

#define NEEDLE_TEXT 1
#define NEEDLE_SPEECH 2

#ifdef __cplusplus
extern "C" {
#endif

/* One process-global, non-thread-safe model per kind, text and speech.
   Negative returns indicate failure; call needle_last_error() for the specific
   reason. needle_load reads whichever kind the .cact holds and keeps the other,
   so a build with both models takes one call per model. */
NEEDLE_API int needle_load(
    const unsigned char* cact,
    unsigned long long n
);

/* NEEDLE_TEXT, NEEDLE_SPEECH or both, for the models this process has loaded. */
NEEDLE_API int needle_models(void);

/* Last process-global error, owned by the runtime and valid until the next API call. */
NEEDLE_API const char* needle_last_error(void);

/* needle_init returns the tokenized static-prefix length on success. It can fail
   when the system prompt plus statically-declared tools exceed the context
   window, and reports the measured token count when it does. */
NEEDLE_API int needle_init(
    const char* system_prompt,
    const char* tools_json,
    const char* tool_index_path
);

/* Answers text or speech: exactly one of input and pcm is non-null. Given pcm,
   the engine transcribes the clip with the loaded speech model, answers the
   transcript, and merges the speech fields into the same JSON object under an
   audio_ prefix. needle_set_audio chooses how that transcription runs. */
NEEDLE_API int needle_complete(
    const char* input,
    const float* pcm,
    int samples,
    int max_new_tokens,
    char* out,
    int out_capacity
);

/* Language, keywords and word timestamps for the transcription needle_complete
   runs for itself, with the meanings they have in needle_transcribe. The
   strings are copied. Defaults: detect the language, no keywords, no times. */
NEEDLE_API void needle_set_audio(
    const char* language,
    const char* keywords,
    int word_timestamps
);

NEEDLE_API void needle_reset(void);

/* Transcribes 16 kHz mono float PCM in [-1, 1], at most 30 s, and returns the
   number of tokens generated. language is "en", "de", "fr", "es", "it", "nl" or
   "pl", or NULL to detect it. keywords is NULL or newline-separated words and
   phrases for keyword biasing. out receives JSON with the transcript, the
   language used, the milliseconds to the first token and the decoder's tokens
   per second after it; silence and steady noise give an empty text and language:
   {"text":"...","language":"en","ttft_ms":0.0,"decode_tps":0.0}
   A non-zero word_timestamps adds each word with times in seconds:
   "words":[{"word":"...","start":0.00,"end":0.00,"probability":0.000}] */
NEEDLE_API int needle_transcribe(
    const float* pcm,
    int samples,
    const char* language,
    const char* keywords,
    int word_timestamps,
    char* out,
    int out_capacity
);

/* Embeds text or speech: exactly one of input and pcm is non-null. Text returns
   the model's embedding dimension, speech one row of that width per 80 ms frame,
   flattened. A null output returns the float count without computing. */
NEEDLE_API int needle_embed(
    const char* input,
    const float* pcm,
    int samples,
    float* out,
    int out_capacity
);

#ifdef __cplusplus
}
#endif
#endif