@runanywhere/core 0.16.0

package/android/src/main/include/rac/infrastructure/events/rac_events.h

@@ -0,0 +1,177 @@
+/**
+ * @file rac_events.h
+ * @brief RunAnywhere Commons - Event Publishing and Subscription
+ *
+ * C port of Swift's SDKEvent protocol and EventPublisher from:
+ * Sources/RunAnywhere/Infrastructure/Events/SDKEvent.swift
+ * Sources/RunAnywhere/Infrastructure/Events/EventPublisher.swift
+ *
+ * Events are categorized and can be routed to different destinations
+ * (public EventBus or analytics).
+ */
+
+#ifndef RAC_EVENTS_H
+#define RAC_EVENTS_H
+
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// EVENT DESTINATION - Mirrors Swift's EventDestination
+// =============================================================================
+
+/**
+ * Where an event should be routed.
+ * Mirrors Swift's EventDestination enum.
+ */
+typedef enum rac_event_destination {
+    /** Only to public EventBus (app developers) */
+    RAC_EVENT_DESTINATION_PUBLIC_ONLY = 0,
+    /** Only to analytics/telemetry (backend) */
+    RAC_EVENT_DESTINATION_ANALYTICS_ONLY = 1,
+    /** Both destinations (default) */
+    RAC_EVENT_DESTINATION_ALL = 2,
+} rac_event_destination_t;
+
+// =============================================================================
+// EVENT CATEGORY - Mirrors Swift's EventCategory
+// =============================================================================
+
+/**
+ * Event categories for filtering/grouping.
+ * Mirrors Swift's EventCategory enum.
+ */
+typedef enum rac_event_category {
+    RAC_EVENT_CATEGORY_SDK = 0,
+    RAC_EVENT_CATEGORY_MODEL = 1,
+    RAC_EVENT_CATEGORY_LLM = 2,
+    RAC_EVENT_CATEGORY_STT = 3,
+    RAC_EVENT_CATEGORY_TTS = 4,
+    RAC_EVENT_CATEGORY_VOICE = 5,
+    RAC_EVENT_CATEGORY_STORAGE = 6,
+    RAC_EVENT_CATEGORY_DEVICE = 7,
+    RAC_EVENT_CATEGORY_NETWORK = 8,
+    RAC_EVENT_CATEGORY_ERROR = 9,
+} rac_event_category_t;
+
+// =============================================================================
+// EVENT STRUCTURE - Mirrors Swift's SDKEvent protocol
+// =============================================================================
+
+/**
+ * Event data structure.
+ * Mirrors Swift's SDKEvent protocol properties.
+ */
+typedef struct rac_event {
+    /** Unique identifier for this event instance */
+    const char* id;
+
+    /** Event type string (used for analytics categorization) */
+    const char* type;
+
+    /** Category for filtering/routing */
+    rac_event_category_t category;
+
+    /** Timestamp in milliseconds since epoch */
+    int64_t timestamp_ms;
+
+    /** Optional session ID for grouping related events (can be NULL) */
+    const char* session_id;
+
+    /** Where to route this event */
+    rac_event_destination_t destination;
+
+    /** Event properties as JSON string (can be NULL) */
+    const char* properties_json;
+} rac_event_t;
+
+// =============================================================================
+// EVENT CALLBACK
+// =============================================================================
+
+/**
+ * Event callback function type.
+ *
+ * @param event The event data (valid only during the callback)
+ * @param user_data User-provided context data
+ */
+typedef void (*rac_event_callback_fn)(const rac_event_t* event, void* user_data);
+
+// =============================================================================
+// EVENT API
+// =============================================================================
+
+/**
+ * Subscribes to events of a specific category.
+ *
+ * @param category The category to subscribe to
+ * @param callback The callback function to invoke
+ * @param user_data User data passed to the callback
+ * @return Subscription ID (0 on failure), use with rac_event_unsubscribe
+ *
+ * @note The callback is invoked on the thread that publishes the event.
+ *       Keep callback execution fast to avoid blocking.
+ */
+RAC_API uint64_t rac_event_subscribe(rac_event_category_t category, rac_event_callback_fn callback,
+                                     void* user_data);
+
+/**
+ * Subscribes to all events regardless of category.
+ *
+ * @param callback The callback function to invoke
+ * @param user_data User data passed to the callback
+ * @return Subscription ID (0 on failure)
+ */
+RAC_API uint64_t rac_event_subscribe_all(rac_event_callback_fn callback, void* user_data);
+
+/**
+ * Unsubscribes from events.
+ *
+ * @param subscription_id The subscription ID returned from subscribe
+ */
+RAC_API void rac_event_unsubscribe(uint64_t subscription_id);
+
+/**
+ * Publishes an event to all subscribers.
+ *
+ * This is called by the commons library to publish events.
+ * Swift's EventBridge subscribes to receive and re-publish to Swift consumers.
+ *
+ * @param event The event to publish
+ * @return RAC_SUCCESS on success, or an error code on failure
+ */
+RAC_API rac_result_t rac_event_publish(const rac_event_t* event);
+
+/**
+ * Track an event (convenience function matching Swift's EventPublisher.track).
+ *
+ * @param type Event type string
+ * @param category Event category
+ * @param destination Where to route this event
+ * @param properties_json Event properties as JSON (can be NULL)
+ * @return RAC_SUCCESS on success, or an error code on failure
+ */
+RAC_API rac_result_t rac_event_track(const char* type, rac_event_category_t category,
+                                     rac_event_destination_t destination,
+                                     const char* properties_json);
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Gets a string name for an event category.
+ *
+ * @param category The event category
+ * @return A string name (never NULL)
+ */
+RAC_API const char* rac_event_category_name(rac_event_category_t category);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_EVENTS_H */

package/android/src/main/include/rac/infrastructure/model_management/rac_model_assignment.h

@@ -0,0 +1,169 @@
+/**
+ * @file rac_model_assignment.h
+ * @brief Model Assignment Manager - Fetches models assigned to device from backend
+ *
+ * Handles fetching model assignments from the backend API.
+ * Business logic (caching, JSON parsing, registry saving) is in C++.
+ * Platform SDKs provide HTTP GET callback for network transport.
+ *
+ * Events are emitted via rac_analytics_event_emit().
+ */
+
+#ifndef RAC_MODEL_ASSIGNMENT_H
+#define RAC_MODEL_ASSIGNMENT_H
+
+#include "rac/core/rac_types.h"
+#include "rac/infrastructure/model_management/rac_model_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// CALLBACK TYPES
+// =============================================================================
+
+/**
+ * @brief HTTP response for model assignment fetch
+ */
+typedef struct rac_assignment_http_response {
+    rac_result_t result;        // RAC_SUCCESS on success
+    int32_t status_code;        // HTTP status code (200, 400, etc.)
+    const char* response_body;  // Response JSON (must remain valid during processing)
+    size_t response_length;     // Length of response body
+    const char* error_message;  // Error message (can be NULL)
+} rac_assignment_http_response_t;
+
+/**
+ * @brief Device info for model assignment request
+ */
+typedef struct rac_assignment_device_info {
+    const char* device_type;  // e.g., "iPhone15,2"
+    const char* platform;     // e.g., "iOS"
+} rac_assignment_device_info_t;
+
+/**
+ * Make HTTP GET request for model assignments
+ * @param endpoint Full endpoint URL with query params
+ * @param requires_auth Whether authentication header is required
+ * @param out_response Output parameter for response
+ * @param user_data User-provided context
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+typedef rac_result_t (*rac_assignment_http_get_fn)(const char* endpoint, rac_bool_t requires_auth,
+                                                   rac_assignment_http_response_t* out_response,
+                                                   void* user_data);
+
+/**
+ * Get device info for model assignment request
+ * @param out_info Output parameter for device info
+ * @param user_data User-provided context
+ */
+typedef void (*rac_assignment_get_device_info_fn)(rac_assignment_device_info_t* out_info,
+                                                  void* user_data);
+
+/**
+ * @brief Callback structure for model assignment operations
+ */
+typedef struct rac_assignment_callbacks {
+    /** Make HTTP GET request */
+    rac_assignment_http_get_fn http_get;
+
+    /** Get device info for request */
+    rac_assignment_get_device_info_fn get_device_info;
+
+    /** User data passed to all callbacks */
+    void* user_data;
+} rac_assignment_callbacks_t;
+
+// =============================================================================
+// MODEL ASSIGNMENT API
+// =============================================================================
+
+/**
+ * @brief Set callbacks for model assignment operations
+ *
+ * Must be called before any other model assignment functions.
+ * Typically called during SDK initialization.
+ *
+ * @param callbacks Callback structure (copied internally)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t
+rac_model_assignment_set_callbacks(const rac_assignment_callbacks_t* callbacks);
+
+/**
+ * @brief Fetch model assignments from backend
+ *
+ * Fetches models assigned to this device from the backend API.
+ * Results are cached for cache_timeout_seconds.
+ *
+ * Business logic:
+ * 1. Check cache if not force_refresh
+ * 2. Get device info (via callback)
+ * 3. Build endpoint URL
+ * 4. Make HTTP GET (via callback)
+ * 5. Parse JSON response
+ * 6. Save models to registry
+ * 7. Update cache
+ * 8. Emit analytics event
+ *
+ * @param force_refresh If true, bypass cache
+ * @param out_models Output array of model infos (caller must free with rac_model_info_array_free)
+ * @param out_count Number of models returned
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+RAC_API rac_result_t rac_model_assignment_fetch(rac_bool_t force_refresh,
+                                                rac_model_info_t*** out_models, size_t* out_count);
+
+/**
+ * @brief Get cached model assignments for a specific framework
+ *
+ * Filters cached models by framework. Does not make network request.
+ * Call rac_model_assignment_fetch first to populate cache.
+ *
+ * @param framework Framework to filter by
+ * @param out_models Output array of model infos (caller must free)
+ * @param out_count Number of models returned
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+RAC_API rac_result_t rac_model_assignment_get_by_framework(rac_inference_framework_t framework,
+                                                           rac_model_info_t*** out_models,
+                                                           size_t* out_count);
+
+/**
+ * @brief Get cached model assignments for a specific category
+ *
+ * Filters cached models by category. Does not make network request.
+ * Call rac_model_assignment_fetch first to populate cache.
+ *
+ * @param category Category to filter by
+ * @param out_models Output array of model infos (caller must free)
+ * @param out_count Number of models returned
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+RAC_API rac_result_t rac_model_assignment_get_by_category(rac_model_category_t category,
+                                                          rac_model_info_t*** out_models,
+                                                          size_t* out_count);
+
+/**
+ * @brief Clear model assignment cache
+ *
+ * Clears the in-memory cache. Next fetch will make network request.
+ */
+RAC_API void rac_model_assignment_clear_cache(void);
+
+/**
+ * @brief Set cache timeout in seconds
+ *
+ * Default is 3600 (1 hour).
+ *
+ * @param timeout_seconds Cache timeout in seconds
+ */
+RAC_API void rac_model_assignment_set_cache_timeout(uint32_t timeout_seconds);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_MODEL_ASSIGNMENT_H */

package/android/src/main/include/rac/infrastructure/model_management/rac_model_paths.h

@@ -0,0 +1,258 @@
+/**
+ * @file rac_model_paths.h
+ * @brief Model Path Utilities - Centralized Path Calculation
+ *
+ * C port of Swift's ModelPathUtils from:
+ * Sources/RunAnywhere/Infrastructure/ModelManagement/Utilities/ModelPathUtils.swift
+ *
+ * Path structure: `{base_dir}/RunAnywhere/Models/{framework}/{modelId}/`
+ *
+ * IMPORTANT: This is a direct translation of the Swift implementation.
+ * Do NOT add features not present in the Swift code.
+ */
+
+#ifndef RAC_MODEL_PATHS_H
+#define RAC_MODEL_PATHS_H
+
+#include <stddef.h>
+
+#include "rac/core/rac_error.h"
+#include "rac/core/rac_types.h"
+#include "rac/infrastructure/model_management/rac_model_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+/**
+ * @brief Set the base directory for model storage.
+ *
+ * This must be called before using any path utilities.
+ * On iOS, this would typically be the Documents directory.
+ * The Swift platform adapter should call this during initialization.
+ *
+ * @param base_dir Base directory path (e.g.,
+ * "/var/mobile/Containers/Data/Application/.../Documents")
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_set_base_dir(const char* base_dir);
+
+/**
+ * @brief Get the configured base directory.
+ *
+ * @return Base directory path, or NULL if not configured
+ */
+RAC_API const char* rac_model_paths_get_base_dir(void);
+
+// =============================================================================
+// BASE DIRECTORIES - Mirrors ModelPathUtils base directory methods
+// =============================================================================
+
+/**
+ * @brief Get the base RunAnywhere directory.
+ * Mirrors Swift's ModelPathUtils.getBaseDirectory().
+ *
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_base_directory(char* out_path, size_t path_size);
+
+/**
+ * @brief Get the models directory.
+ * Mirrors Swift's ModelPathUtils.getModelsDirectory().
+ *
+ * Returns: `{base_dir}/RunAnywhere/Models/`
+ *
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_models_directory(char* out_path, size_t path_size);
+
+// =============================================================================
+// FRAMEWORK-SPECIFIC PATHS - Mirrors ModelPathUtils framework methods
+// =============================================================================
+
+/**
+ * @brief Get the directory for a specific framework.
+ * Mirrors Swift's ModelPathUtils.getFrameworkDirectory(framework:).
+ *
+ * Returns: `{base_dir}/RunAnywhere/Models/{framework}/`
+ *
+ * @param framework Inference framework
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_framework_directory(rac_inference_framework_t framework,
+                                                             char* out_path, size_t path_size);
+
+/**
+ * @brief Get the folder for a specific model.
+ * Mirrors Swift's ModelPathUtils.getModelFolder(modelId:framework:).
+ *
+ * Returns: `{base_dir}/RunAnywhere/Models/{framework}/{modelId}/`
+ *
+ * @param model_id Model identifier
+ * @param framework Inference framework
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_model_folder(const char* model_id,
+                                                      rac_inference_framework_t framework,
+                                                      char* out_path, size_t path_size);
+
+// =============================================================================
+// MODEL FILE PATHS - Mirrors ModelPathUtils file path methods
+// =============================================================================
+
+/**
+ * @brief Get the full path to a model file.
+ * Mirrors Swift's ModelPathUtils.getModelFilePath(modelId:framework:format:).
+ *
+ * Returns: `{base_dir}/RunAnywhere/Models/{framework}/{modelId}/{modelId}.{format}`
+ *
+ * @param model_id Model identifier
+ * @param framework Inference framework
+ * @param format Model format
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_model_file_path(const char* model_id,
+                                                         rac_inference_framework_t framework,
+                                                         rac_model_format_t format, char* out_path,
+                                                         size_t path_size);
+
+/**
+ * @brief Get the expected model path for a model.
+ * Mirrors Swift's ModelPathUtils.getExpectedModelPath(modelId:framework:format:).
+ *
+ * For directory-based frameworks (e.g., ONNX), returns the model folder.
+ * For single-file frameworks (e.g., LlamaCpp), returns the model file path.
+ *
+ * @param model_id Model identifier
+ * @param framework Inference framework
+ * @param format Model format
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_expected_model_path(const char* model_id,
+                                                             rac_inference_framework_t framework,
+                                                             rac_model_format_t format,
+                                                             char* out_path, size_t path_size);
+
+/**
+ * @brief Get the model path from model info.
+ * Mirrors Swift's ModelPathUtils.getModelPath(modelInfo:).
+ *
+ * @param model_info Model information
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_model_path(const rac_model_info_t* model_info,
+                                                    char* out_path, size_t path_size);
+
+// =============================================================================
+// OTHER DIRECTORIES - Mirrors ModelPathUtils other directory methods
+// =============================================================================
+
+/**
+ * @brief Get the cache directory.
+ * Mirrors Swift's ModelPathUtils.getCacheDirectory().
+ *
+ * Returns: `{base_dir}/RunAnywhere/Cache/`
+ *
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_cache_directory(char* out_path, size_t path_size);
+
+/**
+ * @brief Get the temporary files directory.
+ * Mirrors Swift's ModelPathUtils.getTempDirectory().
+ *
+ * Returns: `{base_dir}/RunAnywhere/Temp/`
+ *
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_temp_directory(char* out_path, size_t path_size);
+
+/**
+ * @brief Get the downloads directory.
+ * Mirrors Swift's ModelPathUtils.getDownloadsDirectory().
+ *
+ * Returns: `{base_dir}/RunAnywhere/Downloads/`
+ *
+ * @param out_path Output buffer for path
+ * @param path_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_model_paths_get_downloads_directory(char* out_path, size_t path_size);
+
+// =============================================================================
+// PATH ANALYSIS - Mirrors ModelPathUtils analysis methods
+// =============================================================================
+
+/**
+ * @brief Extract model ID from a file path.
+ * Mirrors Swift's ModelPathUtils.extractModelId(from:).
+ *
+ * @param path File path
+ * @param out_model_id Output buffer for model ID (can be NULL to just check if valid)
+ * @param model_id_size Size of output buffer
+ * @return RAC_SUCCESS if model ID found, RAC_ERROR_NOT_FOUND otherwise
+ */
+RAC_API rac_result_t rac_model_paths_extract_model_id(const char* path, char* out_model_id,
+                                                      size_t model_id_size);
+
+/**
+ * @brief Extract framework from a file path.
+ * Mirrors Swift's ModelPathUtils.extractFramework(from:).
+ *
+ * @param path File path
+ * @param out_framework Output: The framework if found
+ * @return RAC_SUCCESS if framework found, RAC_ERROR_NOT_FOUND otherwise
+ */
+RAC_API rac_result_t rac_model_paths_extract_framework(const char* path,
+                                                       rac_inference_framework_t* out_framework);
+
+/**
+ * @brief Check if a path is within the models directory.
+ * Mirrors Swift's ModelPathUtils.isModelPath(_:).
+ *
+ * @param path File path to check
+ * @return RAC_TRUE if path is within models directory, RAC_FALSE otherwise
+ */
+RAC_API rac_bool_t rac_model_paths_is_model_path(const char* path);
+
+// =============================================================================
+// PATH UTILITIES
+// =============================================================================
+
+// NOTE: rac_model_format_extension is declared in rac_model_types.h
+
+/**
+ * @brief Get raw value string for a framework.
+ *
+ * @param framework Inference framework
+ * @return Raw value string (e.g., "LlamaCpp", "ONNX")
+ */
+RAC_API const char* rac_framework_raw_value(rac_inference_framework_t framework);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_MODEL_PATHS_H */