@runanywhere/core 0.16.0

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

@@ -0,0 +1,163 @@
+/**
+ * @file rac_llm_service.h
+ * @brief RunAnywhere Commons - LLM Service Interface
+ *
+ * Defines the generic LLM service API and vtable for multi-backend dispatch.
+ * Backends (LlamaCpp, Platform, ONNX) implement the vtable and register
+ * with the service registry.
+ */
+
+#ifndef RAC_LLM_SERVICE_H
+#define RAC_LLM_SERVICE_H
+
+#include "rac/core/rac_error.h"
+#include "rac/features/llm/rac_llm_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// SERVICE VTABLE - Backend implementations provide this
+// =============================================================================
+
+/**
+ * LLM Service operations vtable.
+ * Each backend implements these functions and provides a static vtable.
+ */
+typedef struct rac_llm_service_ops {
+    /** Initialize the service with a model path */
+    rac_result_t (*initialize)(void* impl, const char* model_path);
+
+    /** Generate text (blocking) */
+    rac_result_t (*generate)(void* impl, const char* prompt, const rac_llm_options_t* options,
+                             rac_llm_result_t* out_result);
+
+    /** Generate text with streaming callback */
+    rac_result_t (*generate_stream)(void* impl, const char* prompt,
+                                    const rac_llm_options_t* options,
+                                    rac_llm_stream_callback_fn callback, void* user_data);
+
+    /** Get service info */
+    rac_result_t (*get_info)(void* impl, rac_llm_info_t* out_info);
+
+    /** Cancel ongoing generation */
+    rac_result_t (*cancel)(void* impl);
+
+    /** Cleanup/unload model (keeps service alive) */
+    rac_result_t (*cleanup)(void* impl);
+
+    /** Destroy the service */
+    void (*destroy)(void* impl);
+} rac_llm_service_ops_t;
+
+/**
+ * LLM Service instance.
+ * Contains vtable pointer and backend-specific implementation.
+ */
+typedef struct rac_llm_service {
+    /** Vtable with backend operations */
+    const rac_llm_service_ops_t* ops;
+
+    /** Backend-specific implementation handle */
+    void* impl;
+
+    /** Model ID for reference */
+    const char* model_id;
+} rac_llm_service_t;
+
+// =============================================================================
+// PUBLIC API - Generic service functions
+// =============================================================================
+
+/**
+ * @brief Create an LLM service
+ *
+ * Routes through service registry to find appropriate backend.
+ *
+ * @param model_id Model identifier (registry ID or path to model file)
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_create(const char* model_id, rac_handle_t* out_handle);
+
+/**
+ * @brief Initialize an LLM service
+ *
+ * @param handle Service handle
+ * @param model_path Path to the model file (can be NULL)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_initialize(rac_handle_t handle, const char* model_path);
+
+/**
+ * @brief Generate text from prompt
+ *
+ * @param handle Service handle
+ * @param prompt Input prompt
+ * @param options Generation options (can be NULL for defaults)
+ * @param out_result Output: Generation result (caller must free with rac_llm_result_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_generate(rac_handle_t handle, const char* prompt,
+                                      const rac_llm_options_t* options,
+                                      rac_llm_result_t* out_result);
+
+/**
+ * @brief Stream generate text token by token
+ *
+ * @param handle Service handle
+ * @param prompt Input prompt
+ * @param options Generation options (can be NULL for defaults)
+ * @param callback Callback for each token
+ * @param user_data User context passed to callback
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_generate_stream(rac_handle_t handle, const char* prompt,
+                                             const rac_llm_options_t* options,
+                                             rac_llm_stream_callback_fn callback, void* user_data);
+
+/**
+ * @brief Get service information
+ *
+ * @param handle Service handle
+ * @param out_info Output: Service information
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_get_info(rac_handle_t handle, rac_llm_info_t* out_info);
+
+/**
+ * @brief Cancel ongoing generation
+ *
+ * @param handle Service handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_cancel(rac_handle_t handle);
+
+/**
+ * @brief Cleanup and release model resources
+ *
+ * @param handle Service handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_llm_cleanup(rac_handle_t handle);
+
+/**
+ * @brief Destroy an LLM service instance
+ *
+ * @param handle Service handle to destroy
+ */
+RAC_API void rac_llm_destroy(rac_handle_t handle);
+
+/**
+ * @brief Free an LLM result
+ *
+ * @param result Result to free
+ */
+RAC_API void rac_llm_result_free(rac_llm_result_t* result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_SERVICE_H */

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

@@ -0,0 +1,141 @@
+/**
+ * @file rac_llm_structured_output.h
+ * @brief RunAnywhere Commons - LLM Structured Output JSON Parsing
+ *
+ * C port of Swift's StructuredOutputHandler.swift from:
+ * Sources/RunAnywhere/Features/LLM/StructuredOutput/StructuredOutputHandler.swift
+ *
+ * IMPORTANT: This is a direct translation of the Swift implementation.
+ * Do NOT add features not present in the Swift code.
+ *
+ * Provides JSON extraction and parsing functions for structured output generation.
+ */
+
+#ifndef RAC_LLM_STRUCTURED_OUTPUT_H
+#define RAC_LLM_STRUCTURED_OUTPUT_H
+
+#include "rac/core/rac_error.h"
+#include "rac/core/rac_types.h"
+#include "rac/features/llm/rac_llm_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// STRUCTURED OUTPUT API
+// =============================================================================
+
+/**
+ * @brief Extract JSON from potentially mixed text
+ *
+ * Ported from Swift StructuredOutputHandler.extractJSON(from:) (lines 102-132)
+ *
+ * Searches for complete JSON objects or arrays in the given text,
+ * handling cases where the text contains additional content before/after JSON.
+ *
+ * @param text Input text that may contain JSON mixed with other content
+ * @param out_json Output: Allocated JSON string (caller must free with rac_free)
+ * @param out_length Output: Length of extracted JSON string (can be NULL)
+ * @return RAC_SUCCESS if JSON found and extracted, error code otherwise
+ */
+RAC_API rac_result_t rac_structured_output_extract_json(const char* text, char** out_json,
+                                                        size_t* out_length);
+
+/**
+ * @brief Find complete JSON boundaries in text
+ *
+ * Ported from Swift StructuredOutputHandler.findCompleteJSON(in:) (lines 135-176)
+ *
+ * Uses a character-by-character state machine to find matching braces/brackets
+ * while properly handling string escapes and nesting.
+ *
+ * @param text Text to search for JSON
+ * @param out_start Output: Start position of JSON (0-indexed)
+ * @param out_end Output: End position of JSON (exclusive)
+ * @return RAC_TRUE if complete JSON found, RAC_FALSE otherwise
+ */
+RAC_API rac_bool_t rac_structured_output_find_complete_json(const char* text, size_t* out_start,
+                                                            size_t* out_end);
+
+/**
+ * @brief Find matching closing brace for an opening brace
+ *
+ * Ported from Swift StructuredOutputHandler.findMatchingBrace(in:startingFrom:) (lines 179-212)
+ *
+ * @param text Text to search
+ * @param start_pos Position of opening brace '{'
+ * @param out_end_pos Output: Position of matching closing brace '}'
+ * @return RAC_TRUE if matching brace found, RAC_FALSE otherwise
+ */
+RAC_API rac_bool_t rac_structured_output_find_matching_brace(const char* text, size_t start_pos,
+                                                             size_t* out_end_pos);
+
+/**
+ * @brief Find matching closing bracket for an opening bracket
+ *
+ * Ported from Swift StructuredOutputHandler.findMatchingBracket(in:startingFrom:) (lines 215-248)
+ *
+ * @param text Text to search
+ * @param start_pos Position of opening bracket '['
+ * @param out_end_pos Output: Position of matching closing bracket ']'
+ * @return RAC_TRUE if matching bracket found, RAC_FALSE otherwise
+ */
+RAC_API rac_bool_t rac_structured_output_find_matching_bracket(const char* text, size_t start_pos,
+                                                               size_t* out_end_pos);
+
+/**
+ * @brief Prepare prompt with structured output instructions
+ *
+ * Ported from Swift StructuredOutputHandler.preparePrompt(originalPrompt:config:) (lines 43-82)
+ *
+ * Adds JSON schema and generation instructions to the prompt.
+ *
+ * @param original_prompt Original user prompt
+ * @param config Structured output configuration with JSON schema
+ * @param out_prompt Output: Allocated prepared prompt (caller must free with rac_free)
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+RAC_API rac_result_t rac_structured_output_prepare_prompt(
+    const char* original_prompt, const rac_structured_output_config_t* config, char** out_prompt);
+
+/**
+ * @brief Get system prompt for structured output generation
+ *
+ * Ported from Swift StructuredOutputHandler.getSystemPrompt(for:) (lines 10-30)
+ *
+ * Generates a system prompt instructing the model to output only valid JSON.
+ *
+ * @param json_schema JSON schema describing expected output structure
+ * @param out_prompt Output: Allocated system prompt (caller must free with rac_free)
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+RAC_API rac_result_t rac_structured_output_get_system_prompt(const char* json_schema,
+                                                             char** out_prompt);
+
+/**
+ * @brief Validate that text contains valid structured output
+ *
+ * Ported from Swift StructuredOutputHandler.validateStructuredOutput(text:config:) (lines 264-282)
+ *
+ * @param text Text to validate
+ * @param config Structured output configuration (can be NULL for basic validation)
+ * @param out_validation Output: Validation result (caller must free extracted_json with rac_free)
+ * @return RAC_SUCCESS on success, error code otherwise
+ */
+RAC_API rac_result_t
+rac_structured_output_validate(const char* text, const rac_structured_output_config_t* config,
+                               rac_structured_output_validation_t* out_validation);
+
+/**
+ * @brief Free structured output validation result
+ *
+ * @param validation Validation result to free
+ */
+RAC_API void rac_structured_output_validation_free(rac_structured_output_validation_t* validation);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_STRUCTURED_OUTPUT_H */

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

@@ -0,0 +1,384 @@
+/**
+ * @file rac_llm_types.h
+ * @brief RunAnywhere Commons - LLM Types and Data Structures
+ *
+ * C port of Swift's LLM Models from:
+ * Sources/RunAnywhere/Features/LLM/Models/LLMGenerationOptions.swift
+ * Sources/RunAnywhere/Features/LLM/Models/LLMGenerationResult.swift
+ *
+ * This header defines data structures only. For the service interface,
+ * see rac_llm_service.h.
+ */
+
+#ifndef RAC_LLM_TYPES_H
+#define RAC_LLM_TYPES_H
+
+#include "rac/core/rac_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// CONFIGURATION - Mirrors Swift's LLMConfiguration
+// =============================================================================
+
+/**
+ * @brief LLM component configuration
+ *
+ * Mirrors Swift's LLMConfiguration struct exactly.
+ * See: Sources/RunAnywhere/Features/LLM/Models/LLMConfiguration.swift
+ */
+typedef struct rac_llm_config {
+    /** Model ID (optional - uses default if NULL) */
+    const char* model_id;
+
+    /** Preferred framework for generation (use RAC_FRAMEWORK_UNKNOWN for auto) */
+    int32_t preferred_framework;
+
+    /** Context length - max tokens the model can handle (default: 2048) */
+    int32_t context_length;
+
+    /** Temperature for sampling (0.0 - 2.0, default: 0.7) */
+    float temperature;
+
+    /** Maximum tokens to generate (default: 100) */
+    int32_t max_tokens;
+
+    /** System prompt for generation (can be NULL) */
+    const char* system_prompt;
+
+    /** Enable streaming mode (default: true) */
+    rac_bool_t streaming_enabled;
+} rac_llm_config_t;
+
+/**
+ * @brief Default LLM configuration
+ */
+static const rac_llm_config_t RAC_LLM_CONFIG_DEFAULT = {.model_id = RAC_NULL,
+                                                        .preferred_framework =
+                                                            99,  // RAC_FRAMEWORK_UNKNOWN
+                                                        .context_length = 2048,
+                                                        .temperature = 0.7f,
+                                                        .max_tokens = 100,
+                                                        .system_prompt = RAC_NULL,
+                                                        .streaming_enabled = RAC_TRUE};
+
+// =============================================================================
+// OPTIONS - Mirrors Swift's LLMGenerationOptions
+// =============================================================================
+
+/**
+ * @brief LLM generation options
+ *
+ * Mirrors Swift's LLMGenerationOptions struct exactly.
+ * See: Sources/RunAnywhere/Features/LLM/Models/LLMGenerationOptions.swift
+ */
+typedef struct rac_llm_options {
+    /** Maximum number of tokens to generate (default: 100) */
+    int32_t max_tokens;
+
+    /** Temperature for sampling (0.0 - 2.0, default: 0.8) */
+    float temperature;
+
+    /** Top-p sampling parameter (default: 1.0) */
+    float top_p;
+
+    /** Stop sequences (null-terminated array, can be NULL) */
+    const char* const* stop_sequences;
+    size_t num_stop_sequences;
+
+    /** Enable streaming mode (default: false) */
+    rac_bool_t streaming_enabled;
+
+    /** System prompt (can be NULL) */
+    const char* system_prompt;
+} rac_llm_options_t;
+
+/**
+ * @brief Default LLM generation options
+ */
+static const rac_llm_options_t RAC_LLM_OPTIONS_DEFAULT = {.max_tokens = 100,
+                                                          .temperature = 0.8f,
+                                                          .top_p = 1.0f,
+                                                          .stop_sequences = RAC_NULL,
+                                                          .num_stop_sequences = 0,
+                                                          .streaming_enabled = RAC_FALSE,
+                                                          .system_prompt = RAC_NULL};
+
+// =============================================================================
+// RESULT - Mirrors Swift's LLMGenerationResult
+// =============================================================================
+
+/**
+ * @brief LLM generation result
+ */
+typedef struct rac_llm_result {
+    /** Generated text (owned, must be freed with rac_free) */
+    char* text;
+
+    /** Number of tokens in prompt */
+    int32_t prompt_tokens;
+
+    /** Number of tokens generated */
+    int32_t completion_tokens;
+
+    /** Total tokens (prompt + completion) */
+    int32_t total_tokens;
+
+    /** Time to first token in milliseconds */
+    int64_t time_to_first_token_ms;
+
+    /** Total generation time in milliseconds */
+    int64_t total_time_ms;
+
+    /** Tokens per second */
+    float tokens_per_second;
+} rac_llm_result_t;
+
+// =============================================================================
+// INFO - Mirrors Swift's LLMService properties
+// =============================================================================
+
+/**
+ * @brief LLM service handle info
+ *
+ * Mirrors Swift's LLMService properties.
+ */
+typedef struct rac_llm_info {
+    /** Whether the service is ready for generation (isReady) */
+    rac_bool_t is_ready;
+
+    /** Current model identifier (currentModel, can be NULL) */
+    const char* current_model;
+
+    /** Context length (contextLength, 0 if unknown) */
+    int32_t context_length;
+
+    /** Whether streaming is supported (supportsStreaming) */
+    rac_bool_t supports_streaming;
+} rac_llm_info_t;
+
+// =============================================================================
+// CALLBACKS
+// =============================================================================
+
+/**
+ * @brief LLM streaming callback
+ *
+ * Called for each generated token during streaming.
+ * Mirrors Swift's onToken callback pattern.
+ *
+ * @param token The generated token string
+ * @param user_data User-provided context
+ * @return RAC_TRUE to continue, RAC_FALSE to stop generation
+ */
+typedef rac_bool_t (*rac_llm_stream_callback_fn)(const char* token, void* user_data);
+
+// =============================================================================
+// THINKING TAG PATTERN - Mirrors Swift's ThinkingTagPattern
+// =============================================================================
+
+/**
+ * @brief Pattern for extracting thinking/reasoning content from model output
+ *
+ * Mirrors Swift's ThinkingTagPattern struct exactly.
+ * See: Sources/RunAnywhere/Features/LLM/Models/ThinkingTagPattern.swift
+ */
+typedef struct rac_thinking_tag_pattern {
+    /** Opening tag for thinking content (e.g., "<think>") */
+    const char* opening_tag;
+
+    /** Closing tag for thinking content (e.g., "</think>") */
+    const char* closing_tag;
+} rac_thinking_tag_pattern_t;
+
+/**
+ * @brief Default thinking tag pattern (DeepSeek/Hermes style)
+ */
+static const rac_thinking_tag_pattern_t RAC_THINKING_TAG_DEFAULT = {.opening_tag = "<think>",
+                                                                    .closing_tag = "</think>"};
+
+/**
+ * @brief Alternative thinking pattern with full word
+ */
+static const rac_thinking_tag_pattern_t RAC_THINKING_TAG_FULL = {.opening_tag = "<thinking>",
+                                                                 .closing_tag = "</thinking>"};
+
+// =============================================================================
+// STRUCTURED OUTPUT - Mirrors Swift's StructuredOutputConfig
+// =============================================================================
+
+/**
+ * @brief Structured output configuration
+ *
+ * Mirrors Swift's StructuredOutputConfig struct.
+ * See: Sources/RunAnywhere/Features/LLM/StructuredOutput/Generatable.swift
+ *
+ * Note: In C, we pass the JSON schema directly instead of using reflection.
+ */
+typedef struct rac_structured_output_config {
+    /** JSON schema for the expected output structure */
+    const char* json_schema;
+
+    /** Whether to include the schema in the prompt */
+    rac_bool_t include_schema_in_prompt;
+} rac_structured_output_config_t;
+
+/**
+ * @brief Default structured output configuration
+ */
+static const rac_structured_output_config_t RAC_STRUCTURED_OUTPUT_DEFAULT = {
+    .json_schema = RAC_NULL, .include_schema_in_prompt = RAC_TRUE};
+
+/**
+ * @brief Structured output validation result
+ *
+ * Mirrors Swift's StructuredOutputValidation struct.
+ */
+typedef struct rac_structured_output_validation {
+    /** Whether the output is valid according to the schema */
+    rac_bool_t is_valid;
+
+    /** Error message if validation failed (can be NULL) */
+    const char* error_message;
+
+    /** Extracted JSON string (can be NULL) */
+    char* extracted_json;
+} rac_structured_output_validation_t;
+
+// =============================================================================
+// STREAMING RESULT - Mirrors Swift's LLMStreamingResult
+// =============================================================================
+
+/**
+ * @brief Token event during streaming
+ *
+ * Provides detailed information about each token during streaming generation.
+ */
+typedef struct rac_llm_token_event {
+    /** The generated token text */
+    const char* token;
+
+    /** Token index in the sequence */
+    int32_t token_index;
+
+    /** Is this the final token? */
+    rac_bool_t is_final;
+
+    /** Tokens generated per second so far */
+    float tokens_per_second;
+} rac_llm_token_event_t;
+
+/**
+ * @brief Extended streaming callback with token event details
+ *
+ * @param event Token event details
+ * @param user_data User-provided context
+ * @return RAC_TRUE to continue, RAC_FALSE to stop generation
+ */
+typedef rac_bool_t (*rac_llm_token_event_callback_fn)(const rac_llm_token_event_t* event,
+                                                      void* user_data);
+
+/**
+ * @brief Streaming result handle
+ *
+ * Opaque handle for managing streaming generation.
+ * In C++, this wraps the streaming state and provides synchronization.
+ *
+ * Note: LLMStreamingResult in Swift returns an AsyncThrowingStream and a Task.
+ * In C, we use callbacks instead of async streams.
+ */
+typedef void* rac_llm_stream_handle_t;
+
+/**
+ * @brief Streaming generation parameters
+ *
+ * Configuration for starting a streaming generation.
+ */
+typedef struct rac_llm_stream_params {
+    /** Prompt to generate from */
+    const char* prompt;
+
+    /** Generation options */
+    rac_llm_options_t options;
+
+    /** Callback for each token */
+    rac_llm_stream_callback_fn on_token;
+
+    /** Extended callback with token event details (optional, can be NULL) */
+    rac_llm_token_event_callback_fn on_token_event;
+
+    /** User data passed to callbacks */
+    void* user_data;
+
+    /** Optional thinking tag pattern to extract thinking content */
+    const rac_thinking_tag_pattern_t* thinking_pattern;
+} rac_llm_stream_params_t;
+
+/**
+ * @brief Streaming generation metrics
+ *
+ * Metrics collected during streaming generation.
+ */
+typedef struct rac_llm_stream_metrics {
+    /** Time to first token in milliseconds */
+    int64_t time_to_first_token_ms;
+
+    /** Total generation time in milliseconds */
+    int64_t total_time_ms;
+
+    /** Number of tokens generated */
+    int32_t tokens_generated;
+
+    /** Tokens per second */
+    float tokens_per_second;
+
+    /** Number of tokens in the prompt */
+    int32_t prompt_tokens;
+
+    /** Thinking tokens if thinking pattern was used */
+    int32_t thinking_tokens;
+
+    /** Response tokens (excluding thinking) */
+    int32_t response_tokens;
+} rac_llm_stream_metrics_t;
+
+/**
+ * @brief Complete streaming result
+ *
+ * Final result after streaming generation is complete.
+ */
+typedef struct rac_llm_stream_result {
+    /** Full generated text (owned, must be freed with rac_free) */
+    char* text;
+
+    /** Extracted thinking content if pattern was provided (can be NULL) */
+    char* thinking_content;
+
+    /** Generation metrics */
+    rac_llm_stream_metrics_t metrics;
+
+    /** Error code if generation failed (RAC_SUCCESS on success) */
+    rac_result_t error_code;
+
+    /** Error message if generation failed (can be NULL) */
+    char* error_message;
+} rac_llm_stream_result_t;
+
+// =============================================================================
+// MEMORY MANAGEMENT
+// =============================================================================
+
+/**
+ * @brief Free LLM result resources
+ *
+ * @param result Result to free (can be NULL)
+ */
+RAC_API void rac_llm_result_free(rac_llm_result_t* result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_LLM_TYPES_H */