@runanywhere/core 0.16.0

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

@@ -0,0 +1,206 @@
+/**
+ * @file rac_telemetry_manager.h
+ * @brief Telemetry manager - handles event queuing, batching, and serialization
+ *
+ * C++ handles all telemetry logic:
+ * - Convert analytics events to telemetry payloads
+ * - Queue and batch events
+ * - Group by modality for production
+ * - Serialize to JSON (environment-aware)
+ * - Callback to platform SDK for HTTP calls
+ *
+ * Platform SDKs only need to:
+ * - Provide device info
+ * - Make HTTP calls when callback is invoked
+ */
+
+#ifndef RAC_TELEMETRY_MANAGER_H
+#define RAC_TELEMETRY_MANAGER_H
+
+#include <RACommons/rac_analytics_events.h>
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_environment.h>
+#include <RACommons/rac_telemetry_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TELEMETRY MANAGER
+// =============================================================================
+
+/**
+ * @brief Opaque telemetry manager handle
+ */
+typedef struct rac_telemetry_manager rac_telemetry_manager_t;
+
+/**
+ * @brief HTTP request callback from C++ to platform SDK
+ *
+ * C++ builds the JSON and determines the endpoint.
+ * Platform SDK just makes the HTTP call.
+ *
+ * @param user_data User data provided at registration
+ * @param endpoint The API endpoint path (e.g., "/api/v1/sdk/telemetry")
+ * @param json_body The JSON request body (null-terminated string)
+ * @param json_length Length of JSON body
+ * @param requires_auth Whether request needs authentication
+ */
+typedef void (*rac_telemetry_http_callback_t)(void* user_data, const char* endpoint,
+                                              const char* json_body, size_t json_length,
+                                              rac_bool_t requires_auth);
+
+/**
+ * @brief HTTP response callback from platform SDK to C++
+ *
+ * Platform SDK calls this after HTTP completes.
+ *
+ * @param manager The telemetry manager
+ * @param success Whether HTTP call succeeded
+ * @param response_json Response JSON (can be NULL on failure)
+ * @param error_message Error message if failed (can be NULL)
+ */
+RAC_API void rac_telemetry_manager_http_complete(rac_telemetry_manager_t* manager,
+                                                 rac_bool_t success, const char* response_json,
+                                                 const char* error_message);
+
+// =============================================================================
+// LIFECYCLE
+// =============================================================================
+
+/**
+ * @brief Create telemetry manager
+ *
+ * @param env SDK environment (determines endpoint and encoding)
+ * @param device_id Persistent device UUID (from Keychain)
+ * @param platform Platform string ("ios", "android", etc.)
+ * @param sdk_version SDK version string
+ * @return Manager handle or NULL on failure
+ */
+RAC_API rac_telemetry_manager_t* rac_telemetry_manager_create(rac_environment_t env,
+                                                              const char* device_id,
+                                                              const char* platform,
+                                                              const char* sdk_version);
+
+/**
+ * @brief Destroy telemetry manager
+ */
+RAC_API void rac_telemetry_manager_destroy(rac_telemetry_manager_t* manager);
+
+/**
+ * @brief Set device info for telemetry payloads
+ *
+ * Call this after creating the manager to set device details.
+ */
+RAC_API void rac_telemetry_manager_set_device_info(rac_telemetry_manager_t* manager,
+                                                   const char* device_model,
+                                                   const char* os_version);
+
+/**
+ * @brief Register HTTP callback
+ *
+ * Platform SDK must register this to receive HTTP requests.
+ */
+RAC_API void rac_telemetry_manager_set_http_callback(rac_telemetry_manager_t* manager,
+                                                     rac_telemetry_http_callback_t callback,
+                                                     void* user_data);
+
+// =============================================================================
+// EVENT TRACKING
+// =============================================================================
+
+/**
+ * @brief Track a telemetry payload directly
+ *
+ * Queues the payload for batching and sending.
+ */
+RAC_API rac_result_t rac_telemetry_manager_track(rac_telemetry_manager_t* manager,
+                                                 const rac_telemetry_payload_t* payload);
+
+/**
+ * @brief Track from analytics event data
+ *
+ * Converts analytics event to telemetry payload and queues it.
+ */
+RAC_API rac_result_t rac_telemetry_manager_track_analytics(rac_telemetry_manager_t* manager,
+                                                           rac_event_type_t event_type,
+                                                           const rac_analytics_event_data_t* data);
+
+/**
+ * @brief Flush queued events immediately
+ *
+ * Sends all queued events to the backend.
+ */
+RAC_API rac_result_t rac_telemetry_manager_flush(rac_telemetry_manager_t* manager);
+
+// =============================================================================
+// JSON SERIALIZATION
+// =============================================================================
+
+/**
+ * @brief Serialize telemetry payload to JSON
+ *
+ * @param payload The payload to serialize
+ * @param env Environment (affects field names and which fields to include)
+ * @param out_json Output: JSON string (caller must free with rac_free)
+ * @param out_length Output: Length of JSON string
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_telemetry_manager_payload_to_json(const rac_telemetry_payload_t* payload,
+                                                           rac_environment_t env, char** out_json,
+                                                           size_t* out_length);
+
+/**
+ * @brief Serialize batch request to JSON
+ *
+ * @param request The batch request
+ * @param env Environment
+ * @param out_json Output: JSON string (caller must free with rac_free)
+ * @param out_length Output: Length of JSON string
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t
+rac_telemetry_manager_batch_to_json(const rac_telemetry_batch_request_t* request,
+                                    rac_environment_t env, char** out_json, size_t* out_length);
+
+/**
+ * @brief Parse batch response from JSON
+ *
+ * @param json JSON response string
+ * @param out_response Output: Parsed response (caller must free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_telemetry_manager_parse_response(
+    const char* json, rac_telemetry_batch_response_t* out_response);
+
+// =============================================================================
+// DEVICE REGISTRATION
+// =============================================================================
+
+/**
+ * @brief Serialize device registration request to JSON
+ *
+ * @param request The registration request
+ * @param env Environment
+ * @param out_json Output: JSON string (caller must free with rac_free)
+ * @param out_length Output: Length of JSON string
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t
+rac_device_registration_to_json(const rac_device_registration_request_t* request,
+                                rac_environment_t env, char** out_json, size_t* out_length);
+
+/**
+ * @brief Get device registration endpoint for environment
+ *
+ * @param env Environment
+ * @return Endpoint path string (static, do not free)
+ */
+RAC_API const char* rac_device_registration_endpoint(rac_environment_t env);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RAC_TELEMETRY_MANAGER_H

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

@@ -0,0 +1,234 @@
+/**
+ * @file rac_telemetry_types.h
+ * @brief Telemetry data structures - canonical source of truth
+ *
+ * All telemetry payloads are defined here. Platform SDKs (Swift, Kotlin, Flutter)
+ * use these types directly or create thin wrappers.
+ *
+ * Mirrors Swift's TelemetryEventPayload.swift structure.
+ */
+
+#ifndef RAC_TELEMETRY_TYPES_H
+#define RAC_TELEMETRY_TYPES_H
+
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_environment.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TELEMETRY EVENT PAYLOAD
+// =============================================================================
+
+/**
+ * @brief Complete telemetry event payload
+ *
+ * Maps to backend SDKTelemetryEvent schema with all fields for:
+ * - LLM events (tokens, generation times, etc.)
+ * - STT events (audio duration, word count, etc.)
+ * - TTS events (character count, audio size, etc.)
+ * - VAD events (speech duration)
+ * - Model lifecycle events (size, archive type)
+ * - SDK lifecycle events (count)
+ * - Storage events (freed bytes)
+ * - Network events (online status)
+ */
+typedef struct rac_telemetry_payload {
+    // Required fields
+    const char* id;          // Unique event ID (UUID)
+    const char* event_type;  // Event type string
+    int64_t timestamp_ms;    // Unix timestamp in milliseconds
+    int64_t created_at_ms;   // When payload was created
+
+    // Event classification
+    const char* modality;  // "llm", "stt", "tts", "model", "system"
+
+    // Device identification
+    const char* device_id;   // Persistent device UUID
+    const char* session_id;  // Optional session ID
+
+    // Model info
+    const char* model_id;
+    const char* model_name;
+    const char* framework;  // "llamacpp", "onnx", "mlx", etc.
+
+    // Device info
+    const char* device;       // Device model (e.g., "iPhone15,2")
+    const char* os_version;   // OS version (e.g., "17.0")
+    const char* platform;     // "ios", "android", "flutter"
+    const char* sdk_version;  // SDK version string
+
+    // Common performance metrics
+    double processing_time_ms;
+    rac_bool_t success;
+    rac_bool_t has_success;  // Whether success field is set
+    const char* error_message;
+    const char* error_code;
+
+    // LLM-specific fields
+    int32_t input_tokens;
+    int32_t output_tokens;
+    int32_t total_tokens;
+    double tokens_per_second;
+    double time_to_first_token_ms;
+    double prompt_eval_time_ms;
+    double generation_time_ms;
+    int32_t context_length;
+    double temperature;
+    int32_t max_tokens;
+
+    // STT-specific fields
+    double audio_duration_ms;
+    double real_time_factor;
+    int32_t word_count;
+    double confidence;
+    const char* language;
+    rac_bool_t is_streaming;
+    rac_bool_t has_is_streaming;
+    int32_t segment_index;
+
+    // TTS-specific fields
+    int32_t character_count;
+    double characters_per_second;
+    int32_t audio_size_bytes;
+    int32_t sample_rate;
+    const char* voice;
+    double output_duration_ms;
+
+    // Model lifecycle fields
+    int64_t model_size_bytes;
+    const char* archive_type;
+
+    // VAD fields
+    double speech_duration_ms;
+
+    // SDK lifecycle fields
+    int32_t count;
+
+    // Storage fields
+    int64_t freed_bytes;
+
+    // Network fields
+    rac_bool_t is_online;
+    rac_bool_t has_is_online;
+} rac_telemetry_payload_t;
+
+/**
+ * @brief Default/empty telemetry payload
+ */
+RAC_API rac_telemetry_payload_t rac_telemetry_payload_default(void);
+
+/**
+ * @brief Free any allocated strings in a telemetry payload
+ */
+RAC_API void rac_telemetry_payload_free(rac_telemetry_payload_t* payload);
+
+// =============================================================================
+// TELEMETRY BATCH REQUEST
+// =============================================================================
+
+/**
+ * @brief Batch telemetry request for API
+ *
+ * Supports both V1 and V2 storage paths:
+ * - V1 (legacy): modality = NULL → stores in sdk_telemetry_events table
+ * - V2 (normalized): modality = "llm"/"stt"/"tts"/"model" → normalized tables
+ */
+typedef struct rac_telemetry_batch_request {
+    rac_telemetry_payload_t* events;
+    size_t events_count;
+    const char* device_id;
+    int64_t timestamp_ms;
+    const char* modality;  // NULL for V1, "llm"/"stt"/"tts"/"model" for V2
+} rac_telemetry_batch_request_t;
+
+/**
+ * @brief Batch telemetry response from API
+ */
+typedef struct rac_telemetry_batch_response {
+    rac_bool_t success;
+    int32_t events_received;
+    int32_t events_stored;
+    int32_t events_skipped;  // Duplicates skipped
+    const char** errors;     // Array of error messages
+    size_t errors_count;
+    const char* storage_version;  // "V1" or "V2"
+} rac_telemetry_batch_response_t;
+
+/**
+ * @brief Free batch response
+ */
+RAC_API void rac_telemetry_batch_response_free(rac_telemetry_batch_response_t* response);
+
+// =============================================================================
+// DEVICE REGISTRATION TYPES
+// =============================================================================
+
+/**
+ * @brief Device information for registration (telemetry-specific)
+ *
+ * Platform-specific values are passed in from Swift/Kotlin.
+ * Matches backend schemas/device.py DeviceInfo schema.
+ * Note: Named differently from rac_device_info_t to avoid conflict.
+ */
+typedef struct rac_device_registration_info {
+    // Required fields (backend schema)
+    const char* device_id;           // Persistent UUID from Keychain/secure storage
+    const char* device_model;        // "iPhone 16 Pro Max", "Pixel 7", etc.
+    const char* device_name;         // User-assigned device name
+    const char* platform;            // "ios", "android"
+    const char* os_version;          // "17.0", "14"
+    const char* form_factor;         // "phone", "tablet", "laptop", etc.
+    const char* architecture;        // "arm64", "x86_64", etc.
+    const char* chip_name;           // "A18 Pro", "Snapdragon 888", etc.
+    int64_t total_memory;            // Total RAM in bytes
+    int64_t available_memory;        // Available RAM in bytes
+    rac_bool_t has_neural_engine;    // true if device has Neural Engine / NPU
+    int32_t neural_engine_cores;     // Number of Neural Engine cores (0 if none)
+    const char* gpu_family;          // "apple", "adreno", etc.
+    double battery_level;            // 0.0-1.0, negative if unavailable
+    const char* battery_state;       // "charging", "full", "unplugged", NULL if unavailable
+    rac_bool_t is_low_power_mode;    // Low power mode enabled
+    int32_t core_count;              // Total CPU cores
+    int32_t performance_cores;       // Performance (P) cores
+    int32_t efficiency_cores;        // Efficiency (E) cores
+    const char* device_fingerprint;  // Unique device fingerprint (may be same as device_id)
+
+    // Legacy fields (for backward compatibility)
+    const char* device_type;  // "smartphone", "tablet", etc. (deprecated - use form_factor)
+    const char* os_name;      // "iOS", "Android" (deprecated - use platform)
+    int64_t total_disk_bytes;
+    int64_t available_disk_bytes;
+    const char* processor_info;
+    int32_t processor_count;  // Deprecated - use core_count
+    rac_bool_t is_simulator;
+    const char* locale;
+    const char* timezone;
+} rac_device_registration_info_t;
+
+/**
+ * @brief Device registration request
+ */
+typedef struct rac_device_registration_request {
+    rac_device_registration_info_t device_info;
+    const char* sdk_version;
+    const char* build_token;  // For development mode
+    int64_t last_seen_at_ms;
+} rac_device_registration_request_t;
+
+/**
+ * @brief Device registration response
+ */
+typedef struct rac_device_registration_response {
+    const char* device_id;
+    const char* status;       // "registered" or "updated"
+    const char* sync_status;  // "synced" or "pending"
+} rac_device_registration_response_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RAC_TELEMETRY_TYPES_H

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

@@ -0,0 +1,17 @@
+/**
+ * @file rac_tts.h
+ * @brief RunAnywhere Commons - TTS API (Convenience Header)
+ *
+ * This header includes both types and service interface for convenience.
+ * For better separation of concerns, prefer including:
+ * - rac_tts_types.h for data structures only
+ * - rac_tts_service.h for the service interface
+ */
+
+#ifndef RAC_TTS_H
+#define RAC_TTS_H
+
+#include <RACommons/rac_tts_service.h>
+#include <RACommons/rac_tts_types.h>
+
+#endif /* RAC_TTS_H */

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

@@ -0,0 +1,181 @@
+/**
+ * @file rac_tts_analytics.h
+ * @brief TTS analytics service - 1:1 port of TTSAnalyticsService.swift
+ *
+ * Tracks synthesis operations and metrics.
+ * Lifecycle events are handled by the lifecycle manager.
+ *
+ * NOTE: Audio duration estimation assumes 16-bit PCM @ 22050Hz (standard for TTS).
+ * Formula: audioDurationMs = (bytes / 2) / 22050 * 1000
+ *
+ * Swift Source: Sources/RunAnywhere/Features/TTS/Analytics/TTSAnalyticsService.swift
+ */
+
+#ifndef RAC_TTS_ANALYTICS_H
+#define RAC_TTS_ANALYTICS_H
+
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_tts_types.h>
+#include <RACommons/rac_model_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * @brief Opaque handle for TTS analytics service
+ */
+typedef struct rac_tts_analytics_s* rac_tts_analytics_handle_t;
+
+/**
+ * @brief TTS metrics structure
+ * Mirrors Swift's TTSMetrics struct
+ */
+typedef struct rac_tts_metrics {
+    /** Total number of events tracked */
+    int32_t total_events;
+
+    /** Start time (milliseconds since epoch) */
+    int64_t start_time_ms;
+
+    /** Last event time (milliseconds since epoch, 0 if no events) */
+    int64_t last_event_time_ms;
+
+    /** Total number of syntheses */
+    int32_t total_syntheses;
+
+    /** Average synthesis speed (characters processed per second) */
+    double average_characters_per_second;
+
+    /** Average processing time in milliseconds */
+    double average_processing_time_ms;
+
+    /** Average audio duration in milliseconds */
+    double average_audio_duration_ms;
+
+    /** Total characters processed across all syntheses */
+    int32_t total_characters_processed;
+
+    /** Total audio size generated in bytes */
+    int64_t total_audio_size_bytes;
+} rac_tts_metrics_t;
+
+// =============================================================================
+// LIFECYCLE
+// =============================================================================
+
+/**
+ * @brief Create a TTS analytics service instance
+ *
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_tts_analytics_create(rac_tts_analytics_handle_t* out_handle);
+
+/**
+ * @brief Destroy a TTS analytics service instance
+ *
+ * @param handle Handle to destroy
+ */
+RAC_API void rac_tts_analytics_destroy(rac_tts_analytics_handle_t handle);
+
+// =============================================================================
+// SYNTHESIS TRACKING
+// =============================================================================
+
+/**
+ * @brief Start tracking a synthesis
+ *
+ * @param handle Analytics service handle
+ * @param text The text to synthesize
+ * @param voice The voice ID being used
+ * @param sample_rate Audio sample rate in Hz (default: 22050)
+ * @param framework The inference framework being used
+ * @param out_synthesis_id Output: Generated unique ID (owned, must be freed with rac_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_tts_analytics_start_synthesis(rac_tts_analytics_handle_t handle,
+                                                       const char* text, const char* voice,
+                                                       int32_t sample_rate,
+                                                       rac_inference_framework_t framework,
+                                                       char** out_synthesis_id);
+
+/**
+ * @brief Track synthesis chunk (for streaming synthesis)
+ *
+ * @param handle Analytics service handle
+ * @param synthesis_id The synthesis ID
+ * @param chunk_size Size of the chunk in bytes
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_tts_analytics_track_synthesis_chunk(rac_tts_analytics_handle_t handle,
+                                                             const char* synthesis_id,
+                                                             int32_t chunk_size);
+
+/**
+ * @brief Complete a synthesis
+ *
+ * @param handle Analytics service handle
+ * @param synthesis_id The synthesis ID
+ * @param audio_duration_ms Duration of the generated audio in milliseconds
+ * @param audio_size_bytes Size of the generated audio in bytes
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_tts_analytics_complete_synthesis(rac_tts_analytics_handle_t handle,
+                                                          const char* synthesis_id,
+                                                          double audio_duration_ms,
+                                                          int32_t audio_size_bytes);
+
+/**
+ * @brief Track synthesis failure
+ *
+ * @param handle Analytics service handle
+ * @param synthesis_id The synthesis ID
+ * @param error_code Error code
+ * @param error_message Error message
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_tts_analytics_track_synthesis_failed(rac_tts_analytics_handle_t handle,
+                                                              const char* synthesis_id,
+                                                              rac_result_t error_code,
+                                                              const char* error_message);
+
+/**
+ * @brief Track an error during TTS 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 synthesis_id Synthesis ID (can be NULL)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_tts_analytics_track_error(rac_tts_analytics_handle_t handle,
+                                                   rac_result_t error_code,
+                                                   const char* error_message, const char* operation,
+                                                   const char* model_id, const char* synthesis_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_tts_analytics_get_metrics(rac_tts_analytics_handle_t handle,
+                                                   rac_tts_metrics_t* out_metrics);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_TTS_ANALYTICS_H */