@runanywhere/core 0.16.0

package/android/src/main/include/rac/features/llm/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 "rac/core/rac_types.h"
+#include "rac/infrastructure/events/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 */

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

@@ -0,0 +1,402 @@
+/**
+ * @file rac_llm_metrics.h
+ * @brief LLM Streaming Metrics - TTFT and Token Rate Tracking
+ *
+ * C port of Swift's StreamingMetricsCollector and GenerationAnalyticsService.
+ * Swift Source: Sources/RunAnywhere/Features/LLM/LLMCapability.swift (StreamingMetricsCollector)
+ * Swift Source: Sources/RunAnywhere/Features/LLM/Analytics/GenerationAnalyticsService.swift
+ *
+ * IMPORTANT: This is a direct translation of the Swift implementation.
+ * Do NOT add features not present in the Swift code.
+ */
+
+#ifndef RAC_LLM_METRICS_H
+#define RAC_LLM_METRICS_H
+
+#include "rac/core/rac_error.h"
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES - Mirrors Swift's GenerationMetrics and StreamingMetricsCollector
+// =============================================================================
+
+/**
+ * @brief Generation metrics snapshot.
+ * Mirrors Swift's GenerationMetrics struct.
+ */
+typedef struct rac_generation_metrics {
+    /** Total generation count */
+    int32_t total_generations;
+
+    /** Streaming generation count */
+    int32_t streaming_generations;
+
+    /** Non-streaming generation count */
+    int32_t non_streaming_generations;
+
+    /** Average time-to-first-token in ms (streaming only) */
+    double average_ttft_ms;
+
+    /** Average tokens per second */
+    double average_tokens_per_second;
+
+    /** Total input tokens processed */
+    int64_t total_input_tokens;
+
+    /** Total output tokens generated */
+    int64_t total_output_tokens;
+
+    /** Service start time (Unix timestamp ms) */
+    int64_t start_time_ms;
+
+    /** Last event time (Unix timestamp ms) */
+    int64_t last_event_time_ms;
+} rac_generation_metrics_t;
+
+/**
+ * @brief Default generation metrics.
+ */
+static const rac_generation_metrics_t RAC_GENERATION_METRICS_DEFAULT = {
+    .total_generations = 0,
+    .streaming_generations = 0,
+    .non_streaming_generations = 0,
+    .average_ttft_ms = 0.0,
+    .average_tokens_per_second = 0.0,
+    .total_input_tokens = 0,
+    .total_output_tokens = 0,
+    .start_time_ms = 0,
+    .last_event_time_ms = 0};
+
+/**
+ * @brief Streaming generation result.
+ * Mirrors Swift's LLMGenerationResult for streaming.
+ */
+typedef struct rac_streaming_result {
+    /** Generated text (owned, must be freed) */
+    char* text;
+
+    /** Thinking/reasoning content if any (owned, must be freed, can be NULL) */
+    char* thinking_content;
+
+    /** Input tokens processed */
+    int32_t input_tokens;
+
+    /** Output tokens generated */
+    int32_t output_tokens;
+
+    /** Model ID used (owned, must be freed) */
+    char* model_id;
+
+    /** Total latency in milliseconds */
+    double latency_ms;
+
+    /** Tokens generated per second */
+    double tokens_per_second;
+
+    /** Time-to-first-token in milliseconds (0 if not streaming) */
+    double ttft_ms;
+
+    /** Thinking tokens (for reasoning models) */
+    int32_t thinking_tokens;
+
+    /** Response tokens (excluding thinking) */
+    int32_t response_tokens;
+} rac_streaming_result_t;
+
+/**
+ * @brief Default streaming result.
+ */
+static const rac_streaming_result_t RAC_STREAMING_RESULT_DEFAULT = {.text = RAC_NULL,
+                                                                    .thinking_content = RAC_NULL,
+                                                                    .input_tokens = 0,
+                                                                    .output_tokens = 0,
+                                                                    .model_id = RAC_NULL,
+                                                                    .latency_ms = 0.0,
+                                                                    .tokens_per_second = 0.0,
+                                                                    .ttft_ms = 0.0,
+                                                                    .thinking_tokens = 0,
+                                                                    .response_tokens = 0};
+
+// =============================================================================
+// OPAQUE HANDLES
+// =============================================================================
+
+/**
+ * @brief Opaque handle for streaming metrics collector.
+ */
+typedef struct rac_streaming_metrics_collector* rac_streaming_metrics_handle_t;
+
+/**
+ * @brief Opaque handle for generation analytics service.
+ */
+typedef struct rac_generation_analytics* rac_generation_analytics_handle_t;
+
+// =============================================================================
+// STREAMING METRICS COLLECTOR API - Mirrors Swift's StreamingMetricsCollector
+// =============================================================================
+
+/**
+ * @brief Create a streaming metrics collector.
+ *
+ * @param model_id Model ID being used
+ * @param generation_id Unique generation identifier
+ * @param prompt_length Length of input prompt (for token estimation)
+ * @param out_handle Output: Handle to the created collector
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_create(const char* model_id, const char* generation_id,
+                                                  int32_t prompt_length,
+                                                  rac_streaming_metrics_handle_t* out_handle);
+
+/**
+ * @brief Destroy a streaming metrics collector.
+ *
+ * @param handle Collector handle
+ */
+RAC_API void rac_streaming_metrics_destroy(rac_streaming_metrics_handle_t handle);
+
+/**
+ * @brief Mark the start of generation.
+ *
+ * Mirrors Swift's StreamingMetricsCollector.markStart().
+ *
+ * @param handle Collector handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_mark_start(rac_streaming_metrics_handle_t handle);
+
+/**
+ * @brief Record a token received during streaming.
+ *
+ * Mirrors Swift's StreamingMetricsCollector.recordToken(_:).
+ * First call records TTFT.
+ *
+ * @param handle Collector handle
+ * @param token Token string received
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_record_token(rac_streaming_metrics_handle_t handle,
+                                                        const char* token);
+
+/**
+ * @brief Mark generation as complete.
+ *
+ * Mirrors Swift's StreamingMetricsCollector.markComplete().
+ *
+ * @param handle Collector handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_mark_complete(rac_streaming_metrics_handle_t handle);
+
+/**
+ * @brief Mark generation as failed.
+ *
+ * Mirrors Swift's StreamingMetricsCollector.recordError(_:).
+ *
+ * @param handle Collector handle
+ * @param error_code Error code
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_mark_failed(rac_streaming_metrics_handle_t handle,
+                                                       rac_result_t error_code);
+
+/**
+ * @brief Get the generation result.
+ *
+ * Mirrors Swift's StreamingMetricsCollector.buildResult().
+ * Only valid after markComplete() is called.
+ *
+ * @param handle Collector handle
+ * @param out_result Output: Streaming result (must be freed with rac_streaming_result_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_get_result(rac_streaming_metrics_handle_t handle,
+                                                      rac_streaming_result_t* out_result);
+
+/**
+ * @brief Get current TTFT in milliseconds.
+ *
+ * @param handle Collector handle
+ * @param out_ttft_ms Output: TTFT in ms (0 if first token not yet received)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_get_ttft(rac_streaming_metrics_handle_t handle,
+                                                    double* out_ttft_ms);
+
+/**
+ * @brief Get current token count.
+ *
+ * @param handle Collector handle
+ * @param out_token_count Output: Number of tokens recorded
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_get_token_count(rac_streaming_metrics_handle_t handle,
+                                                           int32_t* out_token_count);
+
+/**
+ * @brief Get accumulated text.
+ *
+ * @param handle Collector handle
+ * @param out_text Output: Accumulated text (owned, must be freed)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_get_text(rac_streaming_metrics_handle_t handle,
+                                                    char** out_text);
+
+/**
+ * @brief Set actual token counts from backend.
+ *
+ * Call this with actual token counts from the LLM backend's tokenizer
+ * to get accurate telemetry instead of character-based estimation.
+ *
+ * @param handle Collector handle
+ * @param input_tokens Actual input/prompt token count (0 to use estimation)
+ * @param output_tokens Actual output/completion token count (0 to use estimation)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_streaming_metrics_set_token_counts(rac_streaming_metrics_handle_t handle,
+                                                            int32_t input_tokens,
+                                                            int32_t output_tokens);
+
+// =============================================================================
+// GENERATION ANALYTICS SERVICE API - Mirrors Swift's GenerationAnalyticsService
+// =============================================================================
+
+/**
+ * @brief Create a generation analytics service.
+ *
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_create(rac_generation_analytics_handle_t* out_handle);
+
+/**
+ * @brief Destroy a generation analytics service.
+ *
+ * @param handle Service handle
+ */
+RAC_API void rac_generation_analytics_destroy(rac_generation_analytics_handle_t handle);
+
+/**
+ * @brief Start tracking a non-streaming generation.
+ *
+ * Mirrors Swift's GenerationAnalyticsService.startGeneration().
+ *
+ * @param handle Service handle
+ * @param generation_id Unique generation identifier
+ * @param model_id Model ID
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_start(rac_generation_analytics_handle_t handle,
+                                                    const char* generation_id,
+                                                    const char* model_id);
+
+/**
+ * @brief Start tracking a streaming generation.
+ *
+ * Mirrors Swift's GenerationAnalyticsService.startStreamingGeneration().
+ *
+ * @param handle Service handle
+ * @param generation_id Unique generation identifier
+ * @param model_id Model ID
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_start_streaming(
+    rac_generation_analytics_handle_t handle, const char* generation_id, const char* model_id);
+
+/**
+ * @brief Track first token received (streaming only).
+ *
+ * Mirrors Swift's GenerationAnalyticsService.trackFirstToken().
+ *
+ * @param handle Service handle
+ * @param generation_id Generation identifier
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_track_first_token(
+    rac_generation_analytics_handle_t handle, const char* generation_id);
+
+/**
+ * @brief Track streaming update.
+ *
+ * Mirrors Swift's GenerationAnalyticsService.trackStreamingUpdate().
+ *
+ * @param handle Service handle
+ * @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_generation_analytics_track_streaming_update(
+    rac_generation_analytics_handle_t handle, const char* generation_id, int32_t tokens_generated);
+
+/**
+ * @brief Complete a generation.
+ *
+ * Mirrors Swift's GenerationAnalyticsService.completeGeneration().
+ *
+ * @param handle Service handle
+ * @param generation_id Generation identifier
+ * @param input_tokens Number of input tokens
+ * @param output_tokens Number of output tokens
+ * @param model_id Model ID used
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_complete(rac_generation_analytics_handle_t handle,
+                                                       const char* generation_id,
+                                                       int32_t input_tokens, int32_t output_tokens,
+                                                       const char* model_id);
+
+/**
+ * @brief Track generation failure.
+ *
+ * Mirrors Swift's GenerationAnalyticsService.trackGenerationFailed().
+ *
+ * @param handle Service handle
+ * @param generation_id Generation identifier
+ * @param error_code Error code
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_track_failed(rac_generation_analytics_handle_t handle,
+                                                           const char* generation_id,
+                                                           rac_result_t error_code);
+
+/**
+ * @brief Get aggregated metrics.
+ *
+ * Mirrors Swift's GenerationAnalyticsService.getMetrics().
+ *
+ * @param handle Service handle
+ * @param out_metrics Output: Generation metrics
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_get_metrics(rac_generation_analytics_handle_t handle,
+                                                          rac_generation_metrics_t* out_metrics);
+
+/**
+ * @brief Reset metrics.
+ *
+ * @param handle Service handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_generation_analytics_reset(rac_generation_analytics_handle_t handle);
+
+// =============================================================================
+// MEMORY MANAGEMENT
+// =============================================================================
+
+/**
+ * @brief Free a streaming result.
+ *
+ * @param result Result to free
+ */
+RAC_API void rac_streaming_result_free(rac_streaming_result_t* result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_METRICS_H */