C API VW Setup and Teardown

Current Interface

vw* initialize(config::options_i& options, io_buf* model = nullptr, bool skipModelLoad = false, trace_message_t trace_listener = nullptr, void* trace_context = nullptr); 

vw* initialize(std::string s, io_buf* model = nullptr, bool skipModelLoad = false, trace_message_t trace_listener = nullptr, void* trace_context = nullptr); 

vw* initialize(int argc, char* argv[], io_buf* model = nullptr, bool skipModelLoad = false, trace_message_t trace_listener = nullptr, void* trace_context = nullptr); 

vw* seed_vw_model(vw vw_model, std::string extra_args, trace_message_t trace_listener = nullptr, void* trace_context = nullptr);

// Allows the input command line string to have spaces escaped by '\' 
vw* initialize_escaped(std::string const& s, io_buf* model = nullptr, bool skipModelLoad = false, trace_message_t trace_listener = nullptr, void* trace_context = nullptr); 

void cmd_string_replace_value(std::stringstream*& ss, std::string flag_to_replace, std::string new_value); 

VW_DEPRECATED("By value version is deprecated, pass std::string by const ref instead using `to_argv`") 
char** get_argv_from_string(std::string s, int& argc); 

// The argv array from both of these functions must be freed. 
char** to_argv(std::string const& s, int& argc); 
char** to_argv_escaped(std::string const& s, int& argc); 
void free_args(int argc, char* argv[]); 

const char* are_features_compatible(vw& vw1, vw& vw2); 
/* 
  Call finish() after you are done with the vw instance.  This cleans up memory usage. 
 */ 
void finish(vw& all, bool delete_all = true); 

void sync_stats(vw& all); 

Deprecate

vw* initialize(...); // Deprecate. Replace with initialize_escaped 

void cmd_string_replace_value(std::stringstream*& ss, std::string flag_to_replace, std::string new_value);  // Maybe deprecate?? Not sure what to make of this one 

char** to_argv(std::string const& s, int& argc); 

char** to_argv_escaped(std::string const& s, int& argc); 

void free_args(int argc, char* argv[]);  // Probably worth deprecating these 3 functions. We should just take in a const char* for the commandline options and run these functions on our side if needed 

Proposed

Options

options* create_options() 

ErrorCode add_option_str(options*, const char* opt_name, const char*) 
ErrorCode add_option_int32(options*, const char* opt_name, int32_t) 
ErrorCode add_option_float(options*, const char* opt_name, float) 

// Options that can take in a list of inputs; eg: input files. Are these necessary? 
ErrorCode add_option_list_str(options*, const char* opt_name, const char*) 
ErrorCode add_option_list_int32(options*, const char* opt_name, int32) 
ErrorCode add_option_list_float(options*, const char* opt_name, float)
 
void delete_options(options*)

VW

ErrorCode initialize(options*, bool skipModelLoad, trace_message_t trace_listener, void* trace_context, vw** output)
ErrorCode initialize_with_model(options*, const uint8_t* model, size_t model_size, bool skipModelLoad, trace_message_t trace_listener, void* trace_context, vw** output)
ErrorCode initialize_cmdline_with_model(const char*, const uint8_t* model, size_t model_size, bool skipModelLoad, trace_message_t trace_listener, void* trace_context, vw** output);

ErrorCode seed_vw_model(const vw*, options* opts, trace_message_t trace_listener, void* trace_context, vw**); 
ErrorCode seed_vw_model_cmdline(const vw*, const char* cmdline_opts, trace_message_t trace_listener, void* trace_context, vw**);

const char* are_features_compatible(const vw*, const vw*);    // Probably better to return an enum with enum->string mappings available? 

// finish is now broken up into finish() and delete_vw(). 
void finish(vw* all); 
void delete_vw(vw* all); 
void sync_stats(vw* all);    // This is only used with allreduce. Should we move this up the tech stack into its own wrapper? 

Temporary interfaces

These interfaces are intended to be a temporary shim to allow migration of existing functions to the new interface. These would be removed in a future version of VW.

// Ideally this would exist outside of VW's core library. But for the time being, it needs to be part of the core API
ErrorCode cmdline_to_options(const char*, options**)

Possible interface to allow full control/modularity of reduction stack

ReductionStack* create_reduction_stack()  // Create a new empty reduction stack to manually configure it 
ReductionStack* create_reduction_stack_from_vw(vw*)  // Get a reduction stack from a fully realized vw object. This creates a new object which must be destroyed with destroy_reduction_stack 
void destroy_reduction_stack(ReductionStack*) 

ErrorCode create_and_append_reduction(ReductionStack*, ReductionType, const options*) 
ErrorCode pop_reduction(ReductionStack*)  // popping an empty reduction stack 
ErrorCode push_reduction(ReductionStack, reduction)  // Can result in an incompatible reduction error. Operation will still succeed in this case 

size_t get_reductions_count(const ReductionStack*) 
reduction get_reduction(ReductionStack*, size_t index) 

ReductionDataType get_reduction_input_type(const reduction*) 
ReductionDataType get_reduction_output_type(const reduction*) 
ReductionType get_reduction_type(const reduction*) 

float(?) predict(ReductionStack*, example*, size_t num_examples) // Might need to alter the return value to match the type coming out of pytorch. Vector of floats maybe? 

float(?) learn(ReductionStack*, example*, size_t num_examples)