@runanywhere/core 0.16.0

package/android/src/main/include/rac/features/platform/rac_llm_platform.h

@@ -0,0 +1,204 @@
+/**
+ * @file rac_llm_platform.h
+ * @brief RunAnywhere Commons - Platform LLM Backend (Apple Foundation Models)
+ *
+ * C API for platform-native LLM services. On Apple platforms, this uses
+ * Foundation Models (Apple Intelligence). The actual implementation is in
+ * Swift, with C++ providing the registration and callback infrastructure.
+ *
+ * This backend follows the same pattern as LlamaCPP and ONNX backends,
+ * but delegates to Swift via function pointer callbacks since Foundation
+ * Models is a Swift-only framework.
+ */
+
+#ifndef RAC_LLM_PLATFORM_H
+#define RAC_LLM_PLATFORM_H
+
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Opaque handle to platform LLM service */
+typedef struct rac_llm_platform* rac_llm_platform_handle_t;
+
+/**
+ * Platform LLM configuration.
+ * Passed during initialization.
+ */
+typedef struct rac_llm_platform_config {
+    /** Reserved for future use */
+    void* reserved;
+} rac_llm_platform_config_t;
+
+/**
+ * Generation options for platform LLM.
+ */
+typedef struct rac_llm_platform_options {
+    /** Temperature for sampling (0.0 = deterministic, 1.0 = creative) */
+    float temperature;
+    /** Maximum tokens to generate */
+    int32_t max_tokens;
+    /** Reserved for future options */
+    void* reserved;
+} rac_llm_platform_options_t;
+
+// =============================================================================
+// SWIFT CALLBACK TYPES
+// =============================================================================
+
+/**
+ * Callback to check if platform LLM can handle a model ID.
+ * Implemented in Swift.
+ *
+ * @param model_id Model identifier to check (can be NULL)
+ * @param user_data User-provided context
+ * @return RAC_TRUE if this backend can handle the model
+ */
+typedef rac_bool_t (*rac_platform_llm_can_handle_fn)(const char* model_id, void* user_data);
+
+/**
+ * Callback to create platform LLM service.
+ * Implemented in Swift.
+ *
+ * @param model_path Path to model (ignored for built-in)
+ * @param config Configuration options
+ * @param user_data User-provided context
+ * @return Handle to created service (Swift object pointer), or NULL on failure
+ */
+typedef rac_handle_t (*rac_platform_llm_create_fn)(const char* model_path,
+                                                   const rac_llm_platform_config_t* config,
+                                                   void* user_data);
+
+/**
+ * Callback to generate text.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle from create
+ * @param prompt Input prompt
+ * @param options Generation options
+ * @param out_response Output: Generated text (caller must free)
+ * @param user_data User-provided context
+ * @return RAC_SUCCESS or error code
+ */
+typedef rac_result_t (*rac_platform_llm_generate_fn)(rac_handle_t handle, const char* prompt,
+                                                     const rac_llm_platform_options_t* options,
+                                                     char** out_response, void* user_data);
+
+/**
+ * Callback to destroy platform LLM service.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle to destroy
+ * @param user_data User-provided context
+ */
+typedef void (*rac_platform_llm_destroy_fn)(rac_handle_t handle, void* user_data);
+
+/**
+ * Swift callbacks for platform LLM operations.
+ */
+typedef struct rac_platform_llm_callbacks {
+    rac_platform_llm_can_handle_fn can_handle;
+    rac_platform_llm_create_fn create;
+    rac_platform_llm_generate_fn generate;
+    rac_platform_llm_destroy_fn destroy;
+    void* user_data;
+} rac_platform_llm_callbacks_t;
+
+// =============================================================================
+// CALLBACK REGISTRATION
+// =============================================================================
+
+/**
+ * Sets the Swift callbacks for platform LLM operations.
+ * Must be called before using platform LLM services.
+ *
+ * @param callbacks Callback functions (copied internally)
+ * @return RAC_SUCCESS on success
+ */
+RAC_API rac_result_t rac_platform_llm_set_callbacks(const rac_platform_llm_callbacks_t* callbacks);
+
+/**
+ * Gets the current Swift callbacks.
+ *
+ * @return Pointer to callbacks, or NULL if not set
+ */
+RAC_API const rac_platform_llm_callbacks_t* rac_platform_llm_get_callbacks(void);
+
+/**
+ * Checks if Swift callbacks are registered.
+ *
+ * @return RAC_TRUE if callbacks are available
+ */
+RAC_API rac_bool_t rac_platform_llm_is_available(void);
+
+// =============================================================================
+// SERVICE API
+// =============================================================================
+
+/**
+ * Creates a platform LLM service.
+ *
+ * @param model_path Path to model (ignored for built-in, can be NULL)
+ * @param config Configuration options (can be NULL for defaults)
+ * @param out_handle Output: Service handle
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_llm_platform_create(const char* model_path,
+                                             const rac_llm_platform_config_t* config,
+                                             rac_llm_platform_handle_t* out_handle);
+
+/**
+ * Destroys a platform LLM service.
+ *
+ * @param handle Service handle to destroy
+ */
+RAC_API void rac_llm_platform_destroy(rac_llm_platform_handle_t handle);
+
+/**
+ * Generates text using platform LLM.
+ *
+ * @param handle Service handle
+ * @param prompt Input prompt
+ * @param options Generation options (can be NULL for defaults)
+ * @param out_response Output: Generated text (caller must free with free())
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_llm_platform_generate(rac_llm_platform_handle_t handle, const char* prompt,
+                                               const rac_llm_platform_options_t* options,
+                                               char** out_response);
+
+// =============================================================================
+// BACKEND REGISTRATION
+// =============================================================================
+
+/**
+ * Registers the Platform backend with the module and service registries.
+ *
+ * This registers:
+ * - Module: "platform" with TEXT_GENERATION and TTS capabilities
+ * - LLM Provider: "AppleFoundationModels" (priority 50)
+ * - TTS Provider: "SystemTTS" (priority 10)
+ * - Built-in model entries for Foundation Models and System TTS
+ *
+ * @return RAC_SUCCESS on success, or an error code
+ */
+RAC_API rac_result_t rac_backend_platform_register(void);
+
+/**
+ * Unregisters the Platform backend.
+ *
+ * @return RAC_SUCCESS on success, or an error code
+ */
+RAC_API rac_result_t rac_backend_platform_unregister(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_PLATFORM_H */

package/android/src/main/include/rac/features/platform/rac_tts_platform.h

@@ -0,0 +1,197 @@
+/**
+ * @file rac_tts_platform.h
+ * @brief RunAnywhere Commons - Platform TTS Backend (System TTS)
+ *
+ * C API for platform-native TTS services. On Apple platforms, this uses
+ * AVSpeechSynthesizer. The actual implementation is in Swift, with C++
+ * providing the registration and callback infrastructure.
+ *
+ * This backend follows the same pattern as ONNX TTS backend, but delegates
+ * to Swift via function pointer callbacks since AVSpeechSynthesizer is
+ * an Apple-only framework.
+ */
+
+#ifndef RAC_TTS_PLATFORM_H
+#define RAC_TTS_PLATFORM_H
+
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Opaque handle to platform TTS service */
+typedef struct rac_tts_platform* rac_tts_platform_handle_t;
+
+/**
+ * Platform TTS configuration.
+ */
+typedef struct rac_tts_platform_config {
+    /** Voice identifier (can be NULL for default) */
+    const char* voice_id;
+    /** Language code (e.g., "en-US") */
+    const char* language;
+    /** Reserved for future use */
+    void* reserved;
+} rac_tts_platform_config_t;
+
+/**
+ * Synthesis options for platform TTS.
+ */
+typedef struct rac_tts_platform_options {
+    /** Speech rate (0.5 = half speed, 1.0 = normal, 2.0 = double) */
+    float rate;
+    /** Pitch multiplier (0.5 = low, 1.0 = normal, 2.0 = high) */
+    float pitch;
+    /** Volume (0.0 = silent, 1.0 = full) */
+    float volume;
+    /** Voice identifier override (can be NULL) */
+    const char* voice_id;
+    /** Reserved for future options */
+    void* reserved;
+} rac_tts_platform_options_t;
+
+// =============================================================================
+// SWIFT CALLBACK TYPES
+// =============================================================================
+
+/**
+ * Callback to check if platform TTS can handle a voice ID.
+ * Implemented in Swift.
+ *
+ * @param voice_id Voice identifier to check (can be NULL)
+ * @param user_data User-provided context
+ * @return RAC_TRUE if this backend can handle the voice
+ */
+typedef rac_bool_t (*rac_platform_tts_can_handle_fn)(const char* voice_id, void* user_data);
+
+/**
+ * Callback to create platform TTS service.
+ * Implemented in Swift.
+ *
+ * @param config Configuration options
+ * @param user_data User-provided context
+ * @return Handle to created service (Swift object pointer), or NULL on failure
+ */
+typedef rac_handle_t (*rac_platform_tts_create_fn)(const rac_tts_platform_config_t* config,
+                                                   void* user_data);
+
+/**
+ * Callback to synthesize speech.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle from create
+ * @param text Text to synthesize
+ * @param options Synthesis options
+ * @param user_data User-provided context
+ * @return RAC_SUCCESS or error code
+ */
+typedef rac_result_t (*rac_platform_tts_synthesize_fn)(rac_handle_t handle, const char* text,
+                                                       const rac_tts_platform_options_t* options,
+                                                       void* user_data);
+
+/**
+ * Callback to stop speech.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle
+ * @param user_data User-provided context
+ */
+typedef void (*rac_platform_tts_stop_fn)(rac_handle_t handle, void* user_data);
+
+/**
+ * Callback to destroy platform TTS service.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle to destroy
+ * @param user_data User-provided context
+ */
+typedef void (*rac_platform_tts_destroy_fn)(rac_handle_t handle, void* user_data);
+
+/**
+ * Swift callbacks for platform TTS operations.
+ */
+typedef struct rac_platform_tts_callbacks {
+    rac_platform_tts_can_handle_fn can_handle;
+    rac_platform_tts_create_fn create;
+    rac_platform_tts_synthesize_fn synthesize;
+    rac_platform_tts_stop_fn stop;
+    rac_platform_tts_destroy_fn destroy;
+    void* user_data;
+} rac_platform_tts_callbacks_t;
+
+// =============================================================================
+// CALLBACK REGISTRATION
+// =============================================================================
+
+/**
+ * Sets the Swift callbacks for platform TTS operations.
+ * Must be called before using platform TTS services.
+ *
+ * @param callbacks Callback functions (copied internally)
+ * @return RAC_SUCCESS on success
+ */
+RAC_API rac_result_t rac_platform_tts_set_callbacks(const rac_platform_tts_callbacks_t* callbacks);
+
+/**
+ * Gets the current Swift callbacks.
+ *
+ * @return Pointer to callbacks, or NULL if not set
+ */
+RAC_API const rac_platform_tts_callbacks_t* rac_platform_tts_get_callbacks(void);
+
+/**
+ * Checks if Swift callbacks are registered.
+ *
+ * @return RAC_TRUE if callbacks are available
+ */
+RAC_API rac_bool_t rac_platform_tts_is_available(void);
+
+// =============================================================================
+// SERVICE API
+// =============================================================================
+
+/**
+ * Creates a platform TTS service.
+ *
+ * @param config Configuration options (can be NULL for defaults)
+ * @param out_handle Output: Service handle
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_tts_platform_create(const rac_tts_platform_config_t* config,
+                                             rac_tts_platform_handle_t* out_handle);
+
+/**
+ * Destroys a platform TTS service.
+ *
+ * @param handle Service handle to destroy
+ */
+RAC_API void rac_tts_platform_destroy(rac_tts_platform_handle_t handle);
+
+/**
+ * Synthesizes speech using platform TTS.
+ *
+ * @param handle Service handle
+ * @param text Text to synthesize
+ * @param options Synthesis options (can be NULL for defaults)
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_tts_platform_synthesize(rac_tts_platform_handle_t handle, const char* text,
+                                                 const rac_tts_platform_options_t* options);
+
+/**
+ * Stops current speech synthesis.
+ *
+ * @param handle Service handle
+ */
+RAC_API void rac_tts_platform_stop(rac_tts_platform_handle_t handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_TTS_PLATFORM_H */

package/android/src/main/include/rac/features/stt/rac_stt.h

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

package/android/src/main/include/rac/features/stt/rac_stt_analytics.h

@@ -0,0 +1,204 @@
+/**
+ * @file rac_stt_analytics.h
+ * @brief STT analytics service - 1:1 port of STTAnalyticsService.swift
+ *
+ * Tracks transcription operations and metrics.
+ * Lifecycle events are handled by the lifecycle manager.
+ *
+ * NOTE: Audio length estimation assumes 16-bit PCM @ 16kHz (standard for STT).
+ * Formula: audioLengthMs = (bytes / 2) / 16000 * 1000
+ *
+ * NOTE: Real-Time Factor (RTF) will be 0 or undefined for streaming transcription
+ * since audioLengthMs = 0 when audio is processed in chunks of unknown total length.
+ *
+ * Swift Source: Sources/RunAnywhere/Features/STT/Analytics/STTAnalyticsService.swift
+ */
+
+#ifndef RAC_STT_ANALYTICS_H
+#define RAC_STT_ANALYTICS_H
+
+#include "rac/core/rac_types.h"
+#include "rac/features/stt/rac_stt_types.h"
+#include "rac/infrastructure/model_management/rac_model_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * @brief Opaque handle for STT analytics service
+ */
+typedef struct rac_stt_analytics_s* rac_stt_analytics_handle_t;
+
+/**
+ * @brief STT metrics structure
+ * Mirrors Swift's STTMetrics struct
+ */
+typedef struct rac_stt_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 transcriptions */
+    int32_t total_transcriptions;
+
+    /** Average confidence score across all transcriptions (0.0 to 1.0) */
+    float average_confidence;
+
+    /** Average processing latency in milliseconds */
+    double average_latency_ms;
+
+    /** Average real-time factor (processing time / audio length) */
+    double average_real_time_factor;
+
+    /** Total audio processed in milliseconds */
+    double total_audio_processed_ms;
+} rac_stt_metrics_t;
+
+// =============================================================================
+// LIFECYCLE
+// =============================================================================
+
+/**
+ * @brief Create an STT analytics service instance
+ *
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_create(rac_stt_analytics_handle_t* out_handle);
+
+/**
+ * @brief Destroy an STT analytics service instance
+ *
+ * @param handle Handle to destroy
+ */
+RAC_API void rac_stt_analytics_destroy(rac_stt_analytics_handle_t handle);
+
+// =============================================================================
+// TRANSCRIPTION TRACKING
+// =============================================================================
+
+/**
+ * @brief Start tracking a transcription
+ *
+ * @param handle Analytics service handle
+ * @param model_id The STT model identifier
+ * @param audio_length_ms Duration of audio in milliseconds
+ * @param audio_size_bytes Size of audio data in bytes
+ * @param language Language code for transcription
+ * @param is_streaming Whether this is a streaming transcription
+ * @param sample_rate Audio sample rate in Hz (default: 16000)
+ * @param framework The inference framework being used
+ * @param out_transcription_id Output: Generated unique ID (owned, must be freed with rac_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_start_transcription(
+    rac_stt_analytics_handle_t handle, const char* model_id, double audio_length_ms,
+    int32_t audio_size_bytes, const char* language, rac_bool_t is_streaming, int32_t sample_rate,
+    rac_inference_framework_t framework, char** out_transcription_id);
+
+/**
+ * @brief Track partial transcript (for streaming transcription)
+ *
+ * @param handle Analytics service handle
+ * @param text Partial transcript text
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_track_partial_transcript(rac_stt_analytics_handle_t handle,
+                                                                const char* text);
+
+/**
+ * @brief Track final transcript (for streaming transcription)
+ *
+ * @param handle Analytics service handle
+ * @param text Final transcript text
+ * @param confidence Confidence score (0.0 to 1.0)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_track_final_transcript(rac_stt_analytics_handle_t handle,
+                                                              const char* text, float confidence);
+
+/**
+ * @brief Complete a transcription
+ *
+ * @param handle Analytics service handle
+ * @param transcription_id The transcription ID
+ * @param text The transcribed text
+ * @param confidence Confidence score (0.0 to 1.0)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_complete_transcription(rac_stt_analytics_handle_t handle,
+                                                              const char* transcription_id,
+                                                              const char* text, float confidence);
+
+/**
+ * @brief Track transcription failure
+ *
+ * @param handle Analytics service handle
+ * @param transcription_id The transcription ID
+ * @param error_code Error code
+ * @param error_message Error message
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_track_transcription_failed(rac_stt_analytics_handle_t handle,
+                                                                  const char* transcription_id,
+                                                                  rac_result_t error_code,
+                                                                  const char* error_message);
+
+/**
+ * @brief Track language detection
+ *
+ * @param handle Analytics service handle
+ * @param language Detected language code
+ * @param confidence Detection confidence (0.0 to 1.0)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_track_language_detection(rac_stt_analytics_handle_t handle,
+                                                                const char* language,
+                                                                float confidence);
+
+/**
+ * @brief Track an error during STT 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 transcription_id Transcription ID (can be NULL)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_stt_analytics_track_error(rac_stt_analytics_handle_t handle,
+                                                   rac_result_t error_code,
+                                                   const char* error_message, const char* operation,
+                                                   const char* model_id,
+                                                   const char* transcription_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_stt_analytics_get_metrics(rac_stt_analytics_handle_t handle,
+                                                   rac_stt_metrics_t* out_metrics);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_STT_ANALYTICS_H */