@runanywhere/core 0.16.0

package/ios/Binaries/RACommons.xcframework/ios-arm64/RACommons.framework/Headers/rac_logger.h

@@ -0,0 +1,416 @@
+/**
+ * @file rac_logger.h
+ * @brief RunAnywhere Commons - Structured Logging System
+ *
+ * Provides a structured logging system that:
+ * - Routes logs through the platform adapter to Swift/Kotlin
+ * - Captures source location metadata (file, line, function)
+ * - Supports log levels, categories, and structured metadata
+ * - Enables remote telemetry for production error tracking
+ *
+ * Usage:
+ *   RAC_LOG_INFO("LLM", "Model loaded successfully");
+ *   RAC_LOG_ERROR("STT", "Failed to load model: %s", error_msg);
+ *   RAC_LOG_DEBUG("VAD", "Energy level: %.2f", energy);
+ *
+ * With metadata:
+ *   rac_log_with_metadata(RAC_LOG_ERROR, "ONNX", "Load failed",
+ *       (rac_log_metadata_t){
+ *           .model_id = "whisper-tiny",
+ *           .error_code = -100,
+ *           .file = __FILE__,
+ *           .line = __LINE__,
+ *           .function = __func__
+ *       });
+ */
+
+#ifndef RAC_LOGGER_H
+#define RAC_LOGGER_H
+
+#include <stdarg.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <RACommons/rac_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// LOG METADATA STRUCTURE
+// =============================================================================
+
+/**
+ * @brief Metadata attached to a log entry.
+ *
+ * All fields are optional - set to NULL/0 if not applicable.
+ * This metadata flows through to Swift/Kotlin for remote telemetry.
+ */
+typedef struct rac_log_metadata {
+    // Source location (auto-populated by macros)
+    const char* file;     /**< Source file name (use __FILE__) */
+    int32_t line;         /**< Source line number (use __LINE__) */
+    const char* function; /**< Function name (use __func__) */
+
+    // Error context
+    int32_t error_code;    /**< Error code if applicable (0 = none) */
+    const char* error_msg; /**< Additional error message */
+
+    // Model context
+    const char* model_id;  /**< Model ID if applicable */
+    const char* framework; /**< Framework name (e.g., "sherpa-onnx") */
+
+    // Custom key-value pairs (for extensibility)
+    const char* custom_key1;
+    const char* custom_value1;
+    const char* custom_key2;
+    const char* custom_value2;
+} rac_log_metadata_t;
+
+/** Default empty metadata */
+#define RAC_LOG_METADATA_EMPTY                                     \
+    (rac_log_metadata_t) {                                         \
+        NULL, 0, NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL \
+    }
+
+// =============================================================================
+// CORE LOGGING API
+// =============================================================================
+
+/**
+ * @brief Initialize the logging system.
+ *
+ * Call this after rac_set_platform_adapter() to enable logging.
+ * If not called, logs will fall back to stderr.
+ *
+ * @param min_level Minimum log level to output
+ * @return RAC_SUCCESS on success
+ */
+RAC_API rac_result_t rac_logger_init(rac_log_level_t min_level);
+
+/**
+ * @brief Shutdown the logging system.
+ *
+ * Flushes any pending logs.
+ */
+RAC_API void rac_logger_shutdown(void);
+
+/**
+ * @brief Set the minimum log level.
+ *
+ * Messages below this level will be filtered out.
+ *
+ * @param level Minimum log level
+ */
+RAC_API void rac_logger_set_min_level(rac_log_level_t level);
+
+/**
+ * @brief Get the current minimum log level.
+ *
+ * @return Current minimum log level
+ */
+RAC_API rac_log_level_t rac_logger_get_min_level(void);
+
+/**
+ * @brief Enable or disable fallback to stderr when platform adapter unavailable.
+ *
+ * @param enabled Whether to fallback to stderr (default: true)
+ */
+RAC_API void rac_logger_set_stderr_fallback(rac_bool_t enabled);
+
+/**
+ * @brief Enable or disable ALWAYS logging to stderr (in addition to platform adapter).
+ *
+ * When enabled (default: true), logs are ALWAYS written to stderr first,
+ * then forwarded to the platform adapter if available. This is essential
+ * for debugging crashes during static initialization before Swift/Kotlin
+ * is ready to receive logs.
+ *
+ * Set to false in production to reduce duplicate logging overhead.
+ *
+ * @param enabled Whether to always log to stderr (default: true)
+ */
+RAC_API void rac_logger_set_stderr_always(rac_bool_t enabled);
+
+/**
+ * @brief Log a message with metadata.
+ *
+ * This is the main logging function. Use the RAC_LOG_* macros for convenience.
+ *
+ * @param level Log level
+ * @param category Log category (e.g., "LLM", "STT.ONNX")
+ * @param message Log message (can include printf-style format specifiers)
+ * @param metadata Optional metadata (can be NULL)
+ */
+RAC_API void rac_logger_log(rac_log_level_t level, const char* category, const char* message,
+                            const rac_log_metadata_t* metadata);
+
+/**
+ * @brief Log a formatted message with metadata.
+ *
+ * @param level Log level
+ * @param category Log category
+ * @param metadata Optional metadata (can be NULL)
+ * @param format Printf-style format string
+ * @param ... Format arguments
+ */
+RAC_API void rac_logger_logf(rac_log_level_t level, const char* category,
+                             const rac_log_metadata_t* metadata, const char* format, ...);
+
+/**
+ * @brief Log a formatted message (variadic version).
+ *
+ * @param level Log level
+ * @param category Log category
+ * @param metadata Optional metadata
+ * @param format Printf-style format string
+ * @param args Variadic arguments
+ */
+RAC_API void rac_logger_logv(rac_log_level_t level, const char* category,
+                             const rac_log_metadata_t* metadata, const char* format, va_list args);
+
+// =============================================================================
+// CONVENIENCE MACROS
+// =============================================================================
+
+/**
+ * Helper to create metadata with source location.
+ */
+#define RAC_LOG_META_HERE()                                                       \
+    (rac_log_metadata_t) {                                                        \
+        __FILE__, __LINE__, __func__, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL \
+    }
+
+/**
+ * Helper to create metadata with source location and error code.
+ */
+#define RAC_LOG_META_ERROR(code, msg)                                                   \
+    (rac_log_metadata_t) {                                                              \
+        __FILE__, __LINE__, __func__, (code), (msg), NULL, NULL, NULL, NULL, NULL, NULL \
+    }
+
+/**
+ * Helper to create metadata with model context.
+ */
+#define RAC_LOG_META_MODEL(mid, fw)                                                \
+    (rac_log_metadata_t) {                                                         \
+        __FILE__, __LINE__, __func__, 0, NULL, (mid), (fw), NULL, NULL, NULL, NULL \
+    }
+
+// --- Level-specific logging macros with automatic source location ---
+
+#define RAC_LOG_TRACE(category, ...)                                   \
+    do {                                                               \
+        rac_log_metadata_t _meta = RAC_LOG_META_HERE();                \
+        rac_logger_logf(RAC_LOG_TRACE, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+#define RAC_LOG_DEBUG(category, ...)                                   \
+    do {                                                               \
+        rac_log_metadata_t _meta = RAC_LOG_META_HERE();                \
+        rac_logger_logf(RAC_LOG_DEBUG, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+#define RAC_LOG_INFO(category, ...)                                   \
+    do {                                                              \
+        rac_log_metadata_t _meta = RAC_LOG_META_HERE();               \
+        rac_logger_logf(RAC_LOG_INFO, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+#define RAC_LOG_WARNING(category, ...)                                   \
+    do {                                                                 \
+        rac_log_metadata_t _meta = RAC_LOG_META_HERE();                  \
+        rac_logger_logf(RAC_LOG_WARNING, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+#define RAC_LOG_ERROR(category, ...)                                   \
+    do {                                                               \
+        rac_log_metadata_t _meta = RAC_LOG_META_HERE();                \
+        rac_logger_logf(RAC_LOG_ERROR, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+#define RAC_LOG_FATAL(category, ...)                                   \
+    do {                                                               \
+        rac_log_metadata_t _meta = RAC_LOG_META_HERE();                \
+        rac_logger_logf(RAC_LOG_FATAL, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+// --- Error logging with code ---
+
+#define RAC_LOG_ERROR_CODE(category, code, ...)                        \
+    do {                                                               \
+        rac_log_metadata_t _meta = RAC_LOG_META_ERROR(code, NULL);     \
+        rac_logger_logf(RAC_LOG_ERROR, category, &_meta, __VA_ARGS__); \
+    } while (0)
+
+// --- Model context logging ---
+
+#define RAC_LOG_MODEL_INFO(category, model_id, framework, ...)              \
+    do {                                                                    \
+        rac_log_metadata_t _meta = RAC_LOG_META_MODEL(model_id, framework); \
+        rac_logger_logf(RAC_LOG_INFO, category, &_meta, __VA_ARGS__);       \
+    } while (0)
+
+#define RAC_LOG_MODEL_ERROR(category, model_id, framework, ...)             \
+    do {                                                                    \
+        rac_log_metadata_t _meta = RAC_LOG_META_MODEL(model_id, framework); \
+        rac_logger_logf(RAC_LOG_ERROR, category, &_meta, __VA_ARGS__);      \
+    } while (0)
+
+// =============================================================================
+// LEGACY COMPATIBILITY (maps to new logging system)
+// =============================================================================
+
+/**
+ * Legacy log_info macro - maps to RAC_LOG_INFO.
+ * @deprecated Use RAC_LOG_INFO instead.
+ */
+#define log_info(category, ...) RAC_LOG_INFO(category, __VA_ARGS__)
+
+/**
+ * Legacy log_debug macro - maps to RAC_LOG_DEBUG.
+ * @deprecated Use RAC_LOG_DEBUG instead.
+ */
+#define log_debug(category, ...) RAC_LOG_DEBUG(category, __VA_ARGS__)
+
+/**
+ * Legacy log_warning macro - maps to RAC_LOG_WARNING.
+ * @deprecated Use RAC_LOG_WARNING instead.
+ */
+#define log_warning(category, ...) RAC_LOG_WARNING(category, __VA_ARGS__)
+
+/**
+ * Legacy log_error macro - maps to RAC_LOG_ERROR.
+ * @deprecated Use RAC_LOG_ERROR instead.
+ */
+#define log_error(category, ...) RAC_LOG_ERROR(category, __VA_ARGS__)
+
+#ifdef __cplusplus
+}
+#endif
+
+// =============================================================================
+// C++ CONVENIENCE CLASS
+// =============================================================================
+
+#ifdef __cplusplus
+
+#include <sstream>
+#include <string>
+
+namespace rac {
+
+/**
+ * @brief C++ Logger class for convenient logging with RAII.
+ *
+ * Usage:
+ *   rac::Logger log("STT.ONNX");
+ *   log.info("Model loaded: %s", model_id);
+ *   log.error("Failed with code %d", error_code);
+ */
+class Logger {
+   public:
+    explicit Logger(const char* category) : category_(category) {}
+    explicit Logger(const std::string& category) : category_(category.c_str()) {}
+
+    void trace(const char* format, ...) const {
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_TRACE, category_, nullptr, format, args);
+        va_end(args);
+    }
+
+    void debug(const char* format, ...) const {
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_DEBUG, category_, nullptr, format, args);
+        va_end(args);
+    }
+
+    void info(const char* format, ...) const {
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_INFO, category_, nullptr, format, args);
+        va_end(args);
+    }
+
+    void warning(const char* format, ...) const {
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_WARNING, category_, nullptr, format, args);
+        va_end(args);
+    }
+
+    void error(const char* format, ...) const {
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_ERROR, category_, nullptr, format, args);
+        va_end(args);
+    }
+
+    void error(int32_t code, const char* format, ...) const {
+        rac_log_metadata_t meta = RAC_LOG_METADATA_EMPTY;
+        meta.error_code = code;
+
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_ERROR, category_, &meta, format, args);
+        va_end(args);
+    }
+
+    void fatal(const char* format, ...) const {
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_FATAL, category_, nullptr, format, args);
+        va_end(args);
+    }
+
+    // Log with model context
+    void modelInfo(const char* model_id, const char* framework, const char* format, ...) const {
+        rac_log_metadata_t meta = RAC_LOG_METADATA_EMPTY;
+        meta.model_id = model_id;
+        meta.framework = framework;
+
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_INFO, category_, &meta, format, args);
+        va_end(args);
+    }
+
+    void modelError(const char* model_id, const char* framework, int32_t code, const char* format,
+                    ...) const {
+        rac_log_metadata_t meta = RAC_LOG_METADATA_EMPTY;
+        meta.model_id = model_id;
+        meta.framework = framework;
+        meta.error_code = code;
+
+        va_list args;
+        va_start(args, format);
+        rac_logger_logv(RAC_LOG_ERROR, category_, &meta, format, args);
+        va_end(args);
+    }
+
+   private:
+    const char* category_;
+};
+
+// Predefined loggers for common categories
+namespace log {
+inline Logger llm("LLM");
+inline Logger stt("STT");
+inline Logger tts("TTS");
+inline Logger vad("VAD");
+inline Logger onnx("ONNX");
+inline Logger llamacpp("LlamaCpp");
+inline Logger download("Download");
+inline Logger models("Models");
+inline Logger core("Core");
+}  // namespace log
+
+}  // namespace rac
+
+#endif  // __cplusplus
+
+#endif /* RAC_LOGGER_H */

package/ios/Binaries/RACommons.xcframework/ios-arm64/RACommons.framework/Headers/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 <RACommons/rac_types.h>
+#include <RACommons/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 */