@runanywhere/core 0.16.0

package/android/src/main/include/rac/core/rac_types.h

@@ -0,0 +1,264 @@
+/**
+ * @file rac_types.h
+ * @brief RunAnywhere Commons - Common Types and Definitions
+ *
+ * This header defines common types, handle types, and macros used throughout
+ * the runanywhere-commons library. All types use the RAC_ prefix to distinguish
+ * from the underlying runanywhere-core (ra_*) types.
+ */
+
+#ifndef RAC_TYPES_H
+#define RAC_TYPES_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+/**
+ * Null pointer macro for use in static initializers.
+ * Uses nullptr in C++ (preferred by clang-tidy modernize-use-nullptr)
+ * and NULL in C for compatibility.
+ */
+#ifdef __cplusplus
+#define RAC_NULL nullptr
+#else
+#define RAC_NULL NULL
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// API VISIBILITY MACROS
+// =============================================================================
+//
+// RAC_API marks functions that must be visible to FFI (dlsym).
+//
+// CRITICAL: For iOS/Android Flutter FFI, symbols MUST have public visibility
+// even when statically linked. dlsym(RTLD_DEFAULT, ...) can only find symbols
+// with "external" visibility, not "private external".
+//
+// Without visibility("default"), static library symbols get "private external"
+// visibility (due to -fvisibility=hidden), which becomes "non-external" (local)
+// in the final binary - breaking FFI symbol lookup.
+// =============================================================================
+
+#if defined(_WIN32)
+#if defined(RAC_BUILDING_SHARED)
+#define RAC_API __declspec(dllexport)
+#elif defined(RAC_USING_SHARED)
+#define RAC_API __declspec(dllimport)
+#else
+#define RAC_API
+#endif
+#elif defined(__GNUC__) || defined(__clang__)
+// Always use default visibility for FFI compatibility
+// This ensures dlsym() can find symbols even in static libraries
+#define RAC_API __attribute__((visibility("default")))
+#else
+#define RAC_API
+#endif
+
+// =============================================================================
+// RESULT TYPE
+// =============================================================================
+
+/**
+ * Result type for all RAC functions.
+ * - 0 indicates success
+ * - Negative values indicate errors (see rac_error.h)
+ *
+ * Error code ranges:
+ * - runanywhere-core (ra_*): 0 to -99
+ * - runanywhere-commons (rac_*): -100 to -999
+ */
+typedef int32_t rac_result_t;
+
+/** Success result */
+#define RAC_SUCCESS ((rac_result_t)0)
+
+// =============================================================================
+// BOOLEAN TYPE
+// =============================================================================
+
+/** Boolean type for C compatibility */
+typedef int32_t rac_bool_t;
+
+#define RAC_TRUE ((rac_bool_t)1)
+#define RAC_FALSE ((rac_bool_t)0)
+
+// =============================================================================
+// HANDLE TYPES
+// =============================================================================
+
+/**
+ * Opaque handle for internal objects.
+ * Handles should be treated as opaque pointers.
+ */
+typedef void* rac_handle_t;
+
+/** Invalid handle value */
+#define RAC_INVALID_HANDLE ((rac_handle_t)NULL)
+
+// =============================================================================
+// STRING TYPES
+// =============================================================================
+
+/**
+ * String view (non-owning reference to a string).
+ * The string is NOT guaranteed to be null-terminated.
+ */
+typedef struct rac_string_view {
+    const char* data; /**< Pointer to string data */
+    size_t length;    /**< Length in bytes (not including any null terminator) */
+} rac_string_view_t;
+
+/**
+ * Creates a string view from a null-terminated C string.
+ */
+#define RAC_STRING_VIEW(s) ((rac_string_view_t){(s), (s) ? strlen(s) : 0})
+
+// =============================================================================
+// AUDIO TYPES
+// =============================================================================
+
+/**
+ * Audio buffer for STT/VAD operations.
+ * Contains PCM float samples in the range [-1.0, 1.0].
+ */
+typedef struct rac_audio_buffer {
+    const float* samples; /**< PCM float samples */
+    size_t num_samples;   /**< Number of samples */
+    int32_t sample_rate;  /**< Sample rate in Hz (e.g., 16000) */
+    int32_t channels;     /**< Number of channels (1 = mono, 2 = stereo) */
+} rac_audio_buffer_t;
+
+/**
+ * Audio format specification.
+ */
+typedef struct rac_audio_format {
+    int32_t sample_rate;     /**< Sample rate in Hz */
+    int32_t channels;        /**< Number of channels */
+    int32_t bits_per_sample; /**< Bits per sample (16 or 32) */
+} rac_audio_format_t;
+
+// =============================================================================
+// MEMORY INFO
+// =============================================================================
+
+/**
+ * Memory information structure.
+ * Used by the platform adapter to report available memory.
+ */
+typedef struct rac_memory_info {
+    uint64_t total_bytes;     /**< Total physical memory in bytes */
+    uint64_t available_bytes; /**< Available memory in bytes */
+    uint64_t used_bytes;      /**< Used memory in bytes */
+} rac_memory_info_t;
+
+// =============================================================================
+// CAPABILITY TYPES
+// =============================================================================
+
+/**
+ * Capability types supported by backends.
+ * These match the capabilities defined in runanywhere-core.
+ */
+typedef enum rac_capability {
+    RAC_CAPABILITY_UNKNOWN = 0,
+    RAC_CAPABILITY_TEXT_GENERATION = 1, /**< LLM text generation */
+    RAC_CAPABILITY_EMBEDDINGS = 2,      /**< Text embeddings */
+    RAC_CAPABILITY_STT = 3,             /**< Speech-to-text */
+    RAC_CAPABILITY_TTS = 4,             /**< Text-to-speech */
+    RAC_CAPABILITY_VAD = 5,             /**< Voice activity detection */
+    RAC_CAPABILITY_DIARIZATION = 6,     /**< Speaker diarization */
+} rac_capability_t;
+
+/**
+ * Device type for backend execution.
+ */
+typedef enum rac_device {
+    RAC_DEVICE_CPU = 0,
+    RAC_DEVICE_GPU = 1,
+    RAC_DEVICE_NPU = 2,
+    RAC_DEVICE_AUTO = 3,
+} rac_device_t;
+
+// =============================================================================
+// LOG LEVELS
+// =============================================================================
+
+/**
+ * Log level for the logging callback.
+ */
+typedef enum rac_log_level {
+    RAC_LOG_TRACE = 0,
+    RAC_LOG_DEBUG = 1,
+    RAC_LOG_INFO = 2,
+    RAC_LOG_WARNING = 3,
+    RAC_LOG_ERROR = 4,
+    RAC_LOG_FATAL = 5,
+} rac_log_level_t;
+
+// =============================================================================
+// VERSION INFO
+// =============================================================================
+
+/**
+ * Version information structure.
+ */
+typedef struct rac_version {
+    uint16_t major;
+    uint16_t minor;
+    uint16_t patch;
+    const char* string; /**< Version string (e.g., "1.0.0") */
+} rac_version_t;
+
+// =============================================================================
+// UTILITY MACROS
+// =============================================================================
+
+/** Check if a result is a success */
+#define RAC_SUCCEEDED(result) ((result) >= 0)
+
+/** Check if a result is an error */
+#define RAC_FAILED(result) ((result) < 0)
+
+/** Check if a handle is valid */
+#define RAC_IS_VALID_HANDLE(handle) ((handle) != RAC_INVALID_HANDLE)
+
+// =============================================================================
+// MEMORY MANAGEMENT
+// =============================================================================
+
+/**
+ * Frees memory allocated by RAC functions.
+ *
+ * Use this to free strings and buffers returned by RAC functions that
+ * are marked as "must be freed with rac_free".
+ *
+ * @param ptr Pointer to memory to free (can be NULL)
+ */
+RAC_API void rac_free(void* ptr);
+
+/**
+ * Allocates memory using the RAC allocator.
+ *
+ * @param size Number of bytes to allocate
+ * @return Pointer to allocated memory, or NULL on failure
+ */
+RAC_API void* rac_alloc(size_t size);
+
+/**
+ * Duplicates a null-terminated string.
+ *
+ * @param str String to duplicate (can be NULL)
+ * @return Duplicated string (must be freed with rac_free), or NULL if str is NULL
+ */
+RAC_API char* rac_strdup(const char* str);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_TYPES_H */

package/android/src/main/include/rac/features/llm/rac_llm.h

@@ -0,0 +1,17 @@
+/**
+ * @file rac_llm.h
+ * @brief RunAnywhere Commons - LLM API (Convenience Header)
+ *
+ * This header includes both types and service interface for convenience.
+ * For better separation of concerns, prefer including:
+ * - rac_llm_types.h for data structures only
+ * - rac_llm_service.h for the service interface
+ */
+
+#ifndef RAC_LLM_H
+#define RAC_LLM_H
+
+#include "rac/features/llm/rac_llm_service.h"
+#include "rac/features/llm/rac_llm_types.h"
+
+#endif /* RAC_LLM_H */

package/android/src/main/include/rac/features/llm/rac_llm_analytics.h

@@ -0,0 +1,188 @@
+/**
+ * @file rac_llm_analytics.h
+ * @brief LLM Generation analytics service - 1:1 port of GenerationAnalyticsService.swift
+ *
+ * Tracks generation operations and metrics.
+ * Lifecycle events are handled by the lifecycle manager.
+ *
+ * NOTE: Token estimation uses ~4 chars/token (approximation, not exact tokenizer count).
+ * Actual token counts may vary depending on the model's tokenizer and input content.
+ *
+ * Swift Source: Sources/RunAnywhere/Features/LLM/Analytics/GenerationAnalyticsService.swift
+ */
+
+#ifndef RAC_LLM_ANALYTICS_H
+#define RAC_LLM_ANALYTICS_H
+
+#include "rac/core/rac_types.h"
+#include "rac/features/llm/rac_llm_metrics.h"
+#include "rac/features/llm/rac_llm_types.h"
+#include "rac/infrastructure/model_management/rac_model_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * @brief Opaque handle for LLM analytics service
+ */
+typedef struct rac_llm_analytics_s* rac_llm_analytics_handle_t;
+
+// Note: rac_generation_metrics_t is defined in rac_llm_metrics.h
+
+// =============================================================================
+// LIFECYCLE
+// =============================================================================
+
+/**
+ * @brief Create an LLM analytics service instance
+ *
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_create(rac_llm_analytics_handle_t* out_handle);
+
+/**
+ * @brief Destroy an LLM analytics service instance
+ *
+ * @param handle Handle to destroy
+ */
+RAC_API void rac_llm_analytics_destroy(rac_llm_analytics_handle_t handle);
+
+// =============================================================================
+// GENERATION TRACKING
+// =============================================================================
+
+/**
+ * @brief Start tracking a non-streaming generation
+ *
+ * Mirrors Swift's startGeneration()
+ *
+ * @param handle Analytics service handle
+ * @param model_id The model ID being used
+ * @param framework The inference framework type (can be RAC_INFERENCE_FRAMEWORK_UNKNOWN)
+ * @param temperature Generation temperature (NULL for default)
+ * @param max_tokens Maximum tokens to generate (NULL for default)
+ * @param context_length Context window size (NULL for default)
+ * @param out_generation_id Output: Generated unique ID (owned, must be freed with rac_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_start_generation(
+    rac_llm_analytics_handle_t handle, const char* model_id, rac_inference_framework_t framework,
+    const float* temperature, const int32_t* max_tokens, const int32_t* context_length,
+    char** out_generation_id);
+
+/**
+ * @brief Start tracking a streaming generation
+ *
+ * Mirrors Swift's startStreamingGeneration()
+ *
+ * @param handle Analytics service handle
+ * @param model_id The model ID being used
+ * @param framework The inference framework type
+ * @param temperature Generation temperature (NULL for default)
+ * @param max_tokens Maximum tokens to generate (NULL for default)
+ * @param context_length Context window size (NULL for default)
+ * @param out_generation_id Output: Generated unique ID (owned, must be freed with rac_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_start_streaming_generation(
+    rac_llm_analytics_handle_t handle, const char* model_id, rac_inference_framework_t framework,
+    const float* temperature, const int32_t* max_tokens, const int32_t* context_length,
+    char** out_generation_id);
+
+/**
+ * @brief Track first token for streaming generation (TTFT metric)
+ *
+ * Only applicable for streaming generations. Call is ignored for non-streaming.
+ *
+ * @param handle Analytics service handle
+ * @param generation_id The generation ID from start_streaming_generation
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_track_first_token(rac_llm_analytics_handle_t handle,
+                                                         const char* generation_id);
+
+/**
+ * @brief Track streaming update (analytics only)
+ *
+ * Only applicable for streaming generations.
+ *
+ * @param handle Analytics service handle
+ * @param generation_id The generation ID
+ * @param tokens_generated Number of tokens generated so far
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_track_streaming_update(rac_llm_analytics_handle_t handle,
+                                                              const char* generation_id,
+                                                              int32_t tokens_generated);
+
+/**
+ * @brief Complete a generation (works for both streaming and non-streaming)
+ *
+ * @param handle Analytics service handle
+ * @param generation_id The generation ID
+ * @param input_tokens Number of input tokens processed
+ * @param output_tokens Number of output tokens generated
+ * @param model_id The model ID used
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_complete_generation(rac_llm_analytics_handle_t handle,
+                                                           const char* generation_id,
+                                                           int32_t input_tokens,
+                                                           int32_t output_tokens,
+                                                           const char* model_id);
+
+/**
+ * @brief Track generation failure
+ *
+ * @param handle Analytics service handle
+ * @param generation_id The generation ID
+ * @param error_code Error code
+ * @param error_message Error message
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_track_generation_failed(rac_llm_analytics_handle_t handle,
+                                                               const char* generation_id,
+                                                               rac_result_t error_code,
+                                                               const char* error_message);
+
+/**
+ * @brief Track an error during LLM operations
+ *
+ * @param handle Analytics service handle
+ * @param error_code Error code
+ * @param error_message Error message
+ * @param operation Operation that failed
+ * @param model_id Model ID (can be NULL)
+ * @param generation_id Generation ID (can be NULL)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_track_error(rac_llm_analytics_handle_t handle,
+                                                   rac_result_t error_code,
+                                                   const char* error_message, const char* operation,
+                                                   const char* model_id, const char* generation_id);
+
+// =============================================================================
+// METRICS
+// =============================================================================
+
+/**
+ * @brief Get current analytics metrics
+ *
+ * @param handle Analytics service handle
+ * @param out_metrics Output: Metrics structure
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_analytics_get_metrics(rac_llm_analytics_handle_t handle,
+                                                   rac_generation_metrics_t* out_metrics);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_ANALYTICS_H */

package/android/src/main/include/rac/features/llm/rac_llm_component.h

@@ -0,0 +1,228 @@
+/**
+ * @file rac_llm_component.h
+ * @brief RunAnywhere Commons - LLM Capability Component
+ *
+ * C port of Swift's LLMCapability.swift from:
+ * Sources/RunAnywhere/Features/LLM/LLMCapability.swift
+ *
+ * Actor-based LLM capability that owns model lifecycle and generation.
+ * Uses lifecycle manager for unified lifecycle + analytics handling.
+ */
+
+#ifndef RAC_LLM_COMPONENT_H
+#define RAC_LLM_COMPONENT_H
+
+#include "rac/core/capabilities/rac_lifecycle.h"
+#include "rac/core/rac_error.h"
+#include "rac/features/llm/rac_llm_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// NOTE: rac_llm_config_t is defined in rac_llm_types.h (included above)
+
+// =============================================================================
+// STREAMING CALLBACKS - For component-level streaming
+// =============================================================================
+
+/**
+ * @brief Streaming callback for token-by-token generation
+ *
+ * @param token The generated token
+ * @param user_data User-provided context
+ * @return RAC_TRUE to continue, RAC_FALSE to stop
+ */
+typedef rac_bool_t (*rac_llm_component_token_callback_fn)(const char* token, void* user_data);
+
+/**
+ * @brief Streaming completion callback
+ *
+ * Called when streaming is complete with final metrics.
+ *
+ * @param result Final generation result with metrics
+ * @param user_data User-provided context
+ */
+typedef void (*rac_llm_component_complete_callback_fn)(const rac_llm_result_t* result,
+                                                       void* user_data);
+
+/**
+ * @brief Streaming error callback
+ *
+ * Called if streaming fails.
+ *
+ * @param error_code Error code
+ * @param error_message Error message
+ * @param user_data User-provided context
+ */
+typedef void (*rac_llm_component_error_callback_fn)(rac_result_t error_code,
+                                                    const char* error_message, void* user_data);
+
+// =============================================================================
+// LLM COMPONENT API - Mirrors Swift's LLMCapability
+// =============================================================================
+
+/**
+ * @brief Create an LLM capability component
+ *
+ * Mirrors Swift's LLMCapability.init()
+ *
+ * @param out_handle Output: Handle to the component
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_create(rac_handle_t* out_handle);
+
+/**
+ * @brief Configure the LLM component
+ *
+ * Mirrors Swift's LLMCapability.configure(_:)
+ *
+ * @param handle Component handle
+ * @param config Configuration
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_configure(rac_handle_t handle,
+                                                 const rac_llm_config_t* config);
+
+/**
+ * @brief Check if model is loaded
+ *
+ * Mirrors Swift's LLMCapability.isModelLoaded
+ *
+ * @param handle Component handle
+ * @return RAC_TRUE if loaded, RAC_FALSE otherwise
+ */
+RAC_API rac_bool_t rac_llm_component_is_loaded(rac_handle_t handle);
+
+/**
+ * @brief Get current model ID
+ *
+ * Mirrors Swift's LLMCapability.currentModelId
+ *
+ * @param handle Component handle
+ * @return Current model ID (NULL if not loaded)
+ */
+RAC_API const char* rac_llm_component_get_model_id(rac_handle_t handle);
+
+/**
+ * @brief Load a model
+ *
+ * Mirrors Swift's LLMCapability.loadModel(_:)
+ *
+ * @param handle Component handle
+ * @param model_path File path to the model (used for loading) - REQUIRED
+ * @param model_id Model identifier for telemetry (e.g., "smollm2-360m-q8_0")
+ *                 Optional: if NULL, defaults to model_path
+ * @param model_name Human-readable model name (e.g., "SmolLM2 360M Q8_0")
+ *                   Optional: if NULL, defaults to model_id
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_load_model(rac_handle_t handle, const char* model_path,
+                                                  const char* model_id, const char* model_name);
+
+/**
+ * @brief Unload the current model
+ *
+ * Mirrors Swift's LLMCapability.unload()
+ *
+ * @param handle Component handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_unload(rac_handle_t handle);
+
+/**
+ * @brief Cleanup and reset the component
+ *
+ * Mirrors Swift's LLMCapability.cleanup()
+ *
+ * @param handle Component handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_cleanup(rac_handle_t handle);
+
+/**
+ * @brief Cancel ongoing generation
+ *
+ * Mirrors Swift's LLMCapability.cancel()
+ * Best-effort cancellation.
+ *
+ * @param handle Component handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_cancel(rac_handle_t handle);
+
+/**
+ * @brief Generate text (non-streaming)
+ *
+ * Mirrors Swift's LLMCapability.generate(_:options:)
+ *
+ * @param handle Component handle
+ * @param prompt Input prompt
+ * @param options Generation options (can be NULL for defaults)
+ * @param out_result Output: Generation result
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_generate(rac_handle_t handle, const char* prompt,
+                                                const rac_llm_options_t* options,
+                                                rac_llm_result_t* out_result);
+
+/**
+ * @brief Check if streaming is supported
+ *
+ * Mirrors Swift's LLMCapability.supportsStreaming
+ *
+ * @param handle Component handle
+ * @return RAC_TRUE if streaming supported, RAC_FALSE otherwise
+ */
+RAC_API rac_bool_t rac_llm_component_supports_streaming(rac_handle_t handle);
+
+/**
+ * @brief Generate text with streaming
+ *
+ * Mirrors Swift's LLMCapability.generateStream(_:options:)
+ *
+ * @param handle Component handle
+ * @param prompt Input prompt
+ * @param options Generation options (can be NULL for defaults)
+ * @param token_callback Called for each generated token
+ * @param complete_callback Called when generation completes
+ * @param error_callback Called on error
+ * @param user_data User context passed to callbacks
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_generate_stream(
+    rac_handle_t handle, const char* prompt, const rac_llm_options_t* options,
+    rac_llm_component_token_callback_fn token_callback,
+    rac_llm_component_complete_callback_fn complete_callback,
+    rac_llm_component_error_callback_fn error_callback, void* user_data);
+
+/**
+ * @brief Get lifecycle state
+ *
+ * @param handle Component handle
+ * @return Current lifecycle state
+ */
+RAC_API rac_lifecycle_state_t rac_llm_component_get_state(rac_handle_t handle);
+
+/**
+ * @brief Get lifecycle metrics
+ *
+ * @param handle Component handle
+ * @param out_metrics Output: Lifecycle metrics
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_component_get_metrics(rac_handle_t handle,
+                                                   rac_lifecycle_metrics_t* out_metrics);
+
+/**
+ * @brief Destroy the LLM component
+ *
+ * @param handle Component handle
+ */
+RAC_API void rac_llm_component_destroy(rac_handle_t handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_COMPONENT_H */