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
);
Path to model weights directory
Optional: directory of .txt files for RAG. NULL to disable
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
);
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