@runanywhere/core 0.16.0

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

@@ -0,0 +1,218 @@
+/**
+ * @file rac_llm_llamacpp.h
+ * @brief RunAnywhere Core - LlamaCPP Backend RAC API
+ *
+ * Direct RAC API export from runanywhere-core's LlamaCPP backend.
+ * This header defines the public C API for LLM inference using llama.cpp.
+ *
+ * Mirrors Swift's LlamaCPPService implementation pattern.
+ */
+
+#ifndef RAC_LLM_LLAMACPP_H
+#define RAC_LLM_LLAMACPP_H
+
+#include <RACommons/rac_error.h>
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_llm.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// EXPORT MACRO
+// =============================================================================
+
+#if defined(RAC_LLAMACPP_BUILDING)
+#if defined(_WIN32)
+#define RAC_LLAMACPP_API __declspec(dllexport)
+#elif defined(__GNUC__) || defined(__clang__)
+#define RAC_LLAMACPP_API __attribute__((visibility("default")))
+#else
+#define RAC_LLAMACPP_API
+#endif
+#else
+#define RAC_LLAMACPP_API
+#endif
+
+// =============================================================================
+// CONFIGURATION - Mirrors Swift's LlamaCPPGenerationConfig
+// =============================================================================
+
+/**
+ * LlamaCPP-specific configuration.
+ *
+ * Mirrors Swift's LlamaCPPGenerationConfig.
+ */
+typedef struct rac_llm_llamacpp_config {
+    /** Context size (0 = auto-detect from model) */
+    int32_t context_size;
+
+    /** Number of threads (0 = auto-detect) */
+    int32_t num_threads;
+
+    /** Number of layers to offload to GPU (Metal on iOS/macOS) */
+    int32_t gpu_layers;
+
+    /** Batch size for prompt processing */
+    int32_t batch_size;
+} rac_llm_llamacpp_config_t;
+
+/**
+ * Default LlamaCPP configuration.
+ */
+static const rac_llm_llamacpp_config_t RAC_LLM_LLAMACPP_CONFIG_DEFAULT = {
+    .context_size = 0,  // Auto-detect
+    .num_threads = 0,   // Auto-detect
+    .gpu_layers = -1,   // All layers on GPU
+    .batch_size = 512};
+
+// =============================================================================
+// LLAMACPP-SPECIFIC API
+// =============================================================================
+
+/**
+ * Creates a LlamaCPP LLM service.
+ *
+ * Mirrors Swift's LlamaCPPService.initialize(modelPath:)
+ *
+ * @param model_path Path to the GGUF model file
+ * @param config LlamaCPP-specific configuration (can be NULL for defaults)
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_create(const char* model_path,
+                                                      const rac_llm_llamacpp_config_t* config,
+                                                      rac_handle_t* out_handle);
+
+/**
+ * Loads a GGUF model into an existing service.
+ *
+ * Mirrors Swift's LlamaCPPService.loadModel(path:config:)
+ *
+ * @param handle Service handle
+ * @param model_path Path to the GGUF model file
+ * @param config LlamaCPP configuration (can be NULL)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_load_model(rac_handle_t handle,
+                                                          const char* model_path,
+                                                          const rac_llm_llamacpp_config_t* config);
+
+/**
+ * Unloads the current model.
+ *
+ * Mirrors Swift's LlamaCPPService.unloadModel()
+ *
+ * @param handle Service handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_unload_model(rac_handle_t handle);
+
+/**
+ * Checks if a model is loaded.
+ *
+ * Mirrors Swift's LlamaCPPService.isModelLoaded
+ *
+ * @param handle Service handle
+ * @return RAC_TRUE if model is loaded, RAC_FALSE otherwise
+ */
+RAC_LLAMACPP_API rac_bool_t rac_llm_llamacpp_is_model_loaded(rac_handle_t handle);
+
+/**
+ * Generates text completion.
+ *
+ * Mirrors Swift's LlamaCPPService.generate(prompt:config:)
+ *
+ * @param handle Service handle
+ * @param prompt Input prompt text
+ * @param options Generation options (can be NULL for defaults)
+ * @param out_result Output: Generation result (caller must free text with rac_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_generate(rac_handle_t handle, const char* prompt,
+                                                        const rac_llm_options_t* options,
+                                                        rac_llm_result_t* out_result);
+
+/**
+ * Streaming text generation callback.
+ *
+ * Mirrors Swift's streaming callback pattern.
+ *
+ * @param token Generated token string
+ * @param is_final Whether this is the final token
+ * @param user_data User-provided context
+ * @return RAC_TRUE to continue, RAC_FALSE to stop
+ */
+typedef rac_bool_t (*rac_llm_llamacpp_stream_callback_fn)(const char* token, rac_bool_t is_final,
+                                                          void* user_data);
+
+/**
+ * Generates text with streaming callback.
+ *
+ * Mirrors Swift's LlamaCPPService.generateStream(prompt:config:)
+ *
+ * @param handle Service handle
+ * @param prompt Input prompt text
+ * @param options Generation options
+ * @param callback Callback for each token
+ * @param user_data User context passed to callback
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_generate_stream(
+    rac_handle_t handle, const char* prompt, const rac_llm_options_t* options,
+    rac_llm_llamacpp_stream_callback_fn callback, void* user_data);
+
+/**
+ * Cancels ongoing generation.
+ *
+ * Mirrors Swift's LlamaCPPService.cancel()
+ *
+ * @param handle Service handle
+ */
+RAC_LLAMACPP_API void rac_llm_llamacpp_cancel(rac_handle_t handle);
+
+/**
+ * Gets model information as JSON.
+ *
+ * @param handle Service handle
+ * @param out_json Output: JSON string (caller must free with rac_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_llm_llamacpp_get_model_info(rac_handle_t handle, char** out_json);
+
+/**
+ * Destroys a LlamaCPP LLM service.
+ *
+ * @param handle Service handle to destroy
+ */
+RAC_LLAMACPP_API void rac_llm_llamacpp_destroy(rac_handle_t handle);
+
+// =============================================================================
+// BACKEND REGISTRATION
+// =============================================================================
+
+/**
+ * Registers the LlamaCPP backend with the commons module and service registries.
+ *
+ * Should be called once during SDK initialization.
+ * This registers:
+ * - Module: "llamacpp" with TEXT_GENERATION capability
+ * - Service provider: LlamaCPP LLM provider
+ *
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_backend_llamacpp_register(void);
+
+/**
+ * Unregisters the LlamaCPP backend.
+ *
+ * @return RAC_SUCCESS or error code
+ */
+RAC_LLAMACPP_API rac_result_t rac_backend_llamacpp_unregister(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_LLAMACPP_H */

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