Skip to main content

​
Overview

The Cactus C FFI provides a stable ABI for all platform SDKs. All handles are opaque pointers.

​
Types

typedef void* cactus_model_t;
typedef void* cactus_index_t;
typedef void* cactus_stream_transcribe_t;

typedef void (*cactus_token_callback)(
    const char* token,
    uint32_t token_id,
    void* user_data
);

​
Lifecycle

​
cactus_init

Initialize a model. 
cactus_model_t cactus_init(
    const char* model_path,
    const char* corpus_dir,
    bool cache_index
);
​
model_path
string
required
Path to model weights directory
​
corpus_dir
string
Optional: directory of .txt files for RAG. NULL to disable
​
cache_index
boolean
Whether to cache RAG embeddings. false = always rebuild

​
cactus_destroy

void cactus_destroy(cactus_model_t model);

​
cactus_reset

Clear KV cache for new conversation. 
void cactus_reset(cactus_model_t model);

​
cactus_stop

Abort ongoing generation. 
void cactus_stop(cactus_model_t model);

​
Completion

​
cactus_complete

Generate text completion. 
int cactus_complete(
    cactus_model_t model,
    const char* messages_json,
    char* response_buffer,
    size_t buffer_size,
    const char* options_json,
    const char* tools_json,
    cactus_token_callback callback,
    void* user_data
);
Returns 0 on success, -1 on error.

​
Transcription

​
cactus_transcribe

int cactus_transcribe(
    cactus_model_t model,
    const char* audio_file_path,
    const char* prompt,
    char* response_buffer,
    size_t buffer_size,
    const char* options_json,
    cactus_token_callback callback,
    void* user_data,
    const uint8_t* pcm_buffer,
    size_t pcm_buffer_size
);

​
Streaming

cactus_stream_transcribe_t cactus_stream_transcribe_start(
    cactus_model_t model,
    const char* options_json
);

int cactus_stream_transcribe_process(
    cactus_stream_transcribe_t stream,
    const uint8_t* pcm_buffer,
    size_t pcm_buffer_size,
    char* response_buffer,
    size_t buffer_size
);

int cactus_stream_transcribe_stop(
    cactus_stream_transcribe_t stream,
    char* response_buffer,
    size_t buffer_size
);

​
Embeddings

int cactus_embed(
    cactus_model_t model,
    const char* text,
    float* embeddings_buffer,
    size_t buffer_size,
    size_t* embedding_dim,
    bool normalize
);

int cactus_image_embed(
    cactus_model_t model,
    const char* image_path,
    float* embeddings_buffer,
    size_t buffer_size,
    size_t* embedding_dim
);

int cactus_audio_embed(
    cactus_model_t model,
    const char* audio_path,
    float* embeddings_buffer,
    size_t buffer_size,
    size_t* embedding_dim
);

​
Vector Index

cactus_index_t cactus_index_init(
    const char* index_dir,
    size_t embedding_dim
);

int cactus_index_add(
    cactus_index_t index,
    const int* ids,
    const char** documents,
    const char** metadatas,
    const float** embeddings,
    size_t count,
    size_t embedding_dim
);

int cactus_index_query(
    cactus_index_t index,
    const float** embeddings,
    size_t embeddings_count,
    size_t embedding_dim,
    const char* options_json,
    int** id_buffers,
    size_t* id_buffer_sizes,
    float** score_buffers,
    size_t* score_buffer_sizes
);

void cactus_index_destroy(cactus_index_t index);

​
Error Handling

const char* cactus_get_last_error(void);

​
See Also

Python SDK

Python FFI bindings

Swift SDK

Swift FFI bindings

Completion API

Completion details

Vector Index

Index API details