@runanywhere/core 0.16.0

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

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

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

@@ -0,0 +1,215 @@
+/**
+ * @file rac_llm_events.h
+ * @brief LLM-specific event types - 1:1 port of LLMEvent.swift
+ *
+ * All LLM-related events in one place.
+ * Each event declares its destination (public, analytics, or both).
+ *
+ * Swift Source: Sources/RunAnywhere/Features/LLM/Analytics/LLMEvent.swift
+ */
+
+#ifndef RAC_LLM_EVENTS_H
+#define RAC_LLM_EVENTS_H
+
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_events.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// LLM EVENT TYPES
+// =============================================================================
+
+/**
+ * @brief LLM event types enumeration
+ * Mirrors Swift's LLMEvent cases
+ */
+typedef enum rac_llm_event_type {
+    RAC_LLM_EVENT_MODEL_LOAD_STARTED = 0,
+    RAC_LLM_EVENT_MODEL_LOAD_COMPLETED,
+    RAC_LLM_EVENT_MODEL_LOAD_FAILED,
+    RAC_LLM_EVENT_MODEL_UNLOADED,
+    RAC_LLM_EVENT_MODEL_UNLOAD_STARTED,
+    RAC_LLM_EVENT_GENERATION_STARTED,
+    RAC_LLM_EVENT_FIRST_TOKEN,
+    RAC_LLM_EVENT_STREAMING_UPDATE,
+    RAC_LLM_EVENT_GENERATION_COMPLETED,
+    RAC_LLM_EVENT_GENERATION_FAILED,
+} rac_llm_event_type_t;
+
+// =============================================================================
+// LLM EVENT DATA STRUCTURES
+// =============================================================================
+
+/**
+ * @brief Model load event data
+ */
+typedef struct rac_llm_model_load_event {
+    const char* model_id;
+    int64_t model_size_bytes;
+    rac_inference_framework_t framework;
+    double duration_ms;        /**< Only for completed events */
+    rac_result_t error_code;   /**< Only for failed events */
+    const char* error_message; /**< Only for failed events */
+} rac_llm_model_load_event_t;
+
+/**
+ * @brief Generation event data
+ */
+typedef struct rac_llm_generation_event {
+    const char* generation_id;
+    const char* model_id;
+    rac_bool_t is_streaming;
+    rac_inference_framework_t framework;
+
+    /** For completed events */
+    int32_t input_tokens;
+    int32_t output_tokens;
+    double duration_ms;
+    double tokens_per_second;
+    double time_to_first_token_ms; /**< -1 if not applicable */
+    float temperature;
+    int32_t max_tokens;
+    int32_t context_length;
+
+    /** For streaming updates */
+    int32_t tokens_generated;
+
+    /** For failed events */
+    rac_result_t error_code;
+    const char* error_message;
+} rac_llm_generation_event_t;
+
+// =============================================================================
+// EVENT PUBLISHING FUNCTIONS
+// =============================================================================
+
+/**
+ * @brief Publish a model load started event
+ *
+ * @param model_id Model identifier
+ * @param model_size_bytes Size of model in bytes (0 if unknown)
+ * @param framework Inference framework
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_model_load_started(const char* model_id,
+                                                      int64_t model_size_bytes,
+                                                      rac_inference_framework_t framework);
+
+/**
+ * @brief Publish a model load completed event
+ *
+ * @param model_id Model identifier
+ * @param duration_ms Load duration in milliseconds
+ * @param model_size_bytes Size of model in bytes
+ * @param framework Inference framework
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_model_load_completed(const char* model_id, double duration_ms,
+                                                        int64_t model_size_bytes,
+                                                        rac_inference_framework_t framework);
+
+/**
+ * @brief Publish a model load failed event
+ *
+ * @param model_id Model identifier
+ * @param error_code Error code
+ * @param error_message Error message
+ * @param framework Inference framework
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_model_load_failed(const char* model_id, rac_result_t error_code,
+                                                     const char* error_message,
+                                                     rac_inference_framework_t framework);
+
+/**
+ * @brief Publish a model unloaded event
+ *
+ * @param model_id Model identifier
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_model_unloaded(const char* model_id);
+
+/**
+ * @brief Publish a generation started event
+ *
+ * @param generation_id Generation identifier
+ * @param model_id Model identifier
+ * @param is_streaming Whether this is streaming generation
+ * @param framework Inference framework
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_generation_started(const char* generation_id,
+                                                      const char* model_id, rac_bool_t is_streaming,
+                                                      rac_inference_framework_t framework);
+
+/**
+ * @brief Publish a first token event (streaming only)
+ *
+ * @param generation_id Generation identifier
+ * @param model_id Model identifier
+ * @param time_to_first_token_ms Time to first token in milliseconds
+ * @param framework Inference framework
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_first_token(const char* generation_id, const char* model_id,
+                                               double time_to_first_token_ms,
+                                               rac_inference_framework_t framework);
+
+/**
+ * @brief Publish a streaming update event
+ *
+ * @param generation_id Generation identifier
+ * @param tokens_generated Number of tokens generated so far
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_streaming_update(const char* generation_id,
+                                                    int32_t tokens_generated);
+
+/**
+ * @brief Publish a generation completed event
+ *
+ * @param event Generation event data
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_generation_completed(const rac_llm_generation_event_t* event);
+
+/**
+ * @brief Publish a generation failed event
+ *
+ * @param generation_id Generation identifier
+ * @param error_code Error code
+ * @param error_message Error message
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_event_generation_failed(const char* generation_id,
+                                                     rac_result_t error_code,
+                                                     const char* error_message);
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * @brief Get the event type string for an LLM event type
+ *
+ * @param event_type The LLM event type
+ * @return Event type string (never NULL)
+ */
+RAC_API const char* rac_llm_event_type_string(rac_llm_event_type_t event_type);
+
+/**
+ * @brief Get the event destination for an LLM event type
+ *
+ * @param event_type The LLM event type
+ * @return Event destination
+ */
+RAC_API rac_event_destination_t rac_llm_event_destination(rac_llm_event_type_t event_type);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_EVENTS_H */