@runanywhere/core 0.17.7 → 0.18.0

package/ios/Binaries/RACommons.xcframework/ios-arm64_x86_64-simulator/RACommons.framework/Headers/rac_diffusion_platform.h

@@ -0,0 +1,305 @@
+/**
+ * @file rac_diffusion_platform.h
+ * @brief RunAnywhere Commons - Platform Diffusion Backend (Apple ml-stable-diffusion)
+ *
+ * C API for platform-native diffusion services. On Apple platforms, this uses
+ * ml-stable-diffusion with Core ML. 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
+ * ml-stable-diffusion is a Swift-only framework.
+ */
+
+#ifndef RAC_DIFFUSION_PLATFORM_H
+#define RAC_DIFFUSION_PLATFORM_H
+
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_diffusion_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Opaque handle to platform diffusion service */
+typedef struct rac_diffusion_platform* rac_diffusion_platform_handle_t;
+
+/**
+ * Platform diffusion configuration.
+ * Passed during initialization.
+ */
+typedef struct rac_diffusion_platform_config {
+    /** Model variant (SD 1.5, SDXL, etc.) */
+    rac_diffusion_model_variant_t model_variant;
+
+    /** Enable safety checker */
+    rac_bool_t enable_safety_checker;
+
+    /** Reduce memory mode */
+    rac_bool_t reduce_memory;
+
+    /** Compute units to use (0 = auto, 1 = CPU, 2 = GPU, 3 = Neural Engine) */
+    int32_t compute_units;
+
+    /** Reserved for future use */
+    void* reserved;
+} rac_diffusion_platform_config_t;
+
+/**
+ * Generation options for platform diffusion.
+ */
+typedef struct rac_diffusion_platform_options {
+    /** Text prompt */
+    const char* prompt;
+
+    /** Negative prompt */
+    const char* negative_prompt;
+
+    /** Output width */
+    int32_t width;
+
+    /** Output height */
+    int32_t height;
+
+    /** Number of inference steps */
+    int32_t steps;
+
+    /** Guidance scale */
+    float guidance_scale;
+
+    /** Random seed (-1 for random) */
+    int64_t seed;
+
+    /** Scheduler type */
+    rac_diffusion_scheduler_t scheduler;
+
+    /** Reserved for future options */
+    void* reserved;
+} rac_diffusion_platform_options_t;
+
+/**
+ * Platform diffusion result.
+ */
+typedef struct rac_diffusion_platform_result {
+    /** Image data (RGBA format, caller must free) */
+    uint8_t* image_data;
+
+    /** Image data size in bytes */
+    size_t image_size;
+
+    /** Image width */
+    int32_t width;
+
+    /** Image height */
+    int32_t height;
+
+    /** Seed used for generation */
+    int64_t seed_used;
+
+    /** Whether safety check was triggered */
+    rac_bool_t safety_triggered;
+} rac_diffusion_platform_result_t;
+
+// =============================================================================
+// SWIFT CALLBACK TYPES
+// =============================================================================
+
+/**
+ * Callback to check if platform diffusion 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_diffusion_can_handle_fn)(const char* model_id, void* user_data);
+
+/**
+ * Callback to create platform diffusion service.
+ * Implemented in Swift.
+ *
+ * @param model_path Path to model directory
+ * @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_diffusion_create_fn)(
+    const char* model_path, const rac_diffusion_platform_config_t* config, void* user_data);
+
+/**
+ * Callback to generate image.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle from create
+ * @param options Generation options
+ * @param out_result Output: Generated image result
+ * @param user_data User-provided context
+ * @return RAC_SUCCESS or error code
+ */
+typedef rac_result_t (*rac_platform_diffusion_generate_fn)(
+    rac_handle_t handle, const rac_diffusion_platform_options_t* options,
+    rac_diffusion_platform_result_t* out_result, void* user_data);
+
+/**
+ * Progress callback type for Swift.
+ *
+ * @param progress Progress value (0.0-1.0)
+ * @param step Current step
+ * @param total_steps Total steps
+ * @param user_data User-provided context
+ * @return RAC_TRUE to continue, RAC_FALSE to cancel
+ */
+typedef rac_bool_t (*rac_platform_diffusion_progress_fn)(float progress, int32_t step,
+                                                         int32_t total_steps, void* user_data);
+
+/**
+ * Callback to generate image with progress.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle from create
+ * @param options Generation options
+ * @param progress_callback Progress callback
+ * @param progress_user_data User data for progress callback
+ * @param out_result Output: Generated image result
+ * @param user_data User-provided context
+ * @return RAC_SUCCESS or error code
+ */
+typedef rac_result_t (*rac_platform_diffusion_generate_with_progress_fn)(
+    rac_handle_t handle, const rac_diffusion_platform_options_t* options,
+    rac_platform_diffusion_progress_fn progress_callback, void* progress_user_data,
+    rac_diffusion_platform_result_t* out_result, void* user_data);
+
+/**
+ * Callback to cancel generation.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle
+ * @param user_data User-provided context
+ * @return RAC_SUCCESS or error code
+ */
+typedef rac_result_t (*rac_platform_diffusion_cancel_fn)(rac_handle_t handle, void* user_data);
+
+/**
+ * Callback to destroy platform diffusion service.
+ * Implemented in Swift.
+ *
+ * @param handle Service handle to destroy
+ * @param user_data User-provided context
+ */
+typedef void (*rac_platform_diffusion_destroy_fn)(rac_handle_t handle, void* user_data);
+
+/**
+ * Swift callbacks for platform diffusion operations.
+ */
+typedef struct rac_platform_diffusion_callbacks {
+    rac_platform_diffusion_can_handle_fn can_handle;
+    rac_platform_diffusion_create_fn create;
+    rac_platform_diffusion_generate_fn generate;
+    rac_platform_diffusion_generate_with_progress_fn generate_with_progress;
+    rac_platform_diffusion_cancel_fn cancel;
+    rac_platform_diffusion_destroy_fn destroy;
+    void* user_data;
+} rac_platform_diffusion_callbacks_t;
+
+// =============================================================================
+// CALLBACK REGISTRATION
+// =============================================================================
+
+/**
+ * Sets the Swift callbacks for platform diffusion operations.
+ * Must be called before using platform diffusion services.
+ *
+ * @param callbacks Callback functions (copied internally)
+ * @return RAC_SUCCESS on success
+ */
+RAC_API rac_result_t rac_platform_diffusion_set_callbacks(
+    const rac_platform_diffusion_callbacks_t* callbacks);
+
+/**
+ * Gets the current Swift callbacks.
+ *
+ * @return Pointer to callbacks, or NULL if not set
+ */
+RAC_API const rac_platform_diffusion_callbacks_t* rac_platform_diffusion_get_callbacks(void);
+
+/**
+ * Checks if Swift callbacks are registered.
+ *
+ * @return RAC_TRUE if callbacks are available
+ */
+RAC_API rac_bool_t rac_platform_diffusion_is_available(void);
+
+// =============================================================================
+// SERVICE API
+// =============================================================================
+
+/**
+ * Creates a platform diffusion service.
+ *
+ * @param model_path Path to Core ML model directory
+ * @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_diffusion_platform_create(const char* model_path,
+                                                   const rac_diffusion_platform_config_t* config,
+                                                   rac_diffusion_platform_handle_t* out_handle);
+
+/**
+ * Destroys a platform diffusion service.
+ *
+ * @param handle Service handle to destroy
+ */
+RAC_API void rac_diffusion_platform_destroy(rac_diffusion_platform_handle_t handle);
+
+/**
+ * Generates an image using platform diffusion.
+ *
+ * @param handle Service handle
+ * @param options Generation options
+ * @param out_result Output: Generated image
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_diffusion_platform_generate(
+    rac_diffusion_platform_handle_t handle, const rac_diffusion_platform_options_t* options,
+    rac_diffusion_platform_result_t* out_result);
+
+/**
+ * Generates an image with progress reporting.
+ *
+ * @param handle Service handle
+ * @param options Generation options
+ * @param progress_callback Progress callback
+ * @param progress_user_data User data for progress callback
+ * @param out_result Output: Generated image
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_diffusion_platform_generate_with_progress(
+    rac_diffusion_platform_handle_t handle, const rac_diffusion_platform_options_t* options,
+    rac_platform_diffusion_progress_fn progress_callback, void* progress_user_data,
+    rac_diffusion_platform_result_t* out_result);
+
+/**
+ * Cancels ongoing generation.
+ *
+ * @param handle Service handle
+ * @return RAC_SUCCESS on success, or error code
+ */
+RAC_API rac_result_t rac_diffusion_platform_cancel(rac_diffusion_platform_handle_t handle);
+
+/**
+ * Frees a platform diffusion result.
+ *
+ * @param result Result to free
+ */
+RAC_API void rac_diffusion_platform_result_free(rac_diffusion_platform_result_t* result);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_DIFFUSION_PLATFORM_H */

package/ios/Binaries/RACommons.xcframework/ios-arm64_x86_64-simulator/RACommons.framework/Headers/rac_diffusion_service.h

@@ -0,0 +1,187 @@
+/**
+ * @file rac_diffusion_service.h
+ * @brief RunAnywhere Commons - Diffusion Service Interface
+ *
+ * Defines the generic diffusion service API and vtable for multi-backend dispatch.
+ * Backends (CoreML, ONNX, Platform) implement the vtable and register
+ * with the service registry.
+ */
+
+#ifndef RAC_DIFFUSION_SERVICE_H
+#define RAC_DIFFUSION_SERVICE_H
+
+#include <RACommons/rac_error.h>
+#include <RACommons/rac_diffusion_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// SERVICE VTABLE - Backend implementations provide this
+// =============================================================================
+
+/**
+ * Diffusion Service operations vtable.
+ * Each backend implements these functions and provides a static vtable.
+ */
+typedef struct rac_diffusion_service_ops {
+    /** Initialize the service with a model path */
+    rac_result_t (*initialize)(void* impl, const char* model_path,
+                               const rac_diffusion_config_t* config);
+
+    /** Generate image (blocking) */
+    rac_result_t (*generate)(void* impl, const rac_diffusion_options_t* options,
+                             rac_diffusion_result_t* out_result);
+
+    /** Generate image with progress callback */
+    rac_result_t (*generate_with_progress)(void* impl, const rac_diffusion_options_t* options,
+                                           rac_diffusion_progress_callback_fn progress_callback,
+                                           void* user_data, rac_diffusion_result_t* out_result);
+
+    /** Get service info */
+    rac_result_t (*get_info)(void* impl, rac_diffusion_info_t* out_info);
+
+    /** Get supported capabilities as bitmask */
+    uint32_t (*get_capabilities)(void* impl);
+
+    /** 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_diffusion_service_ops_t;
+
+/**
+ * Diffusion Service instance.
+ * Contains vtable pointer and backend-specific implementation.
+ */
+typedef struct rac_diffusion_service {
+    /** Vtable with backend operations */
+    const rac_diffusion_service_ops_t* ops;
+
+    /** Backend-specific implementation handle */
+    void* impl;
+
+    /** Model ID for reference */
+    const char* model_id;
+} rac_diffusion_service_t;
+
+// =============================================================================
+// PUBLIC API - Generic service functions
+// =============================================================================
+
+/**
+ * @brief Create a diffusion service
+ *
+ * Routes through service registry to find appropriate backend.
+ *
+ * @param model_id Model identifier (registry ID or path to model)
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_create(const char* model_id, rac_handle_t* out_handle);
+
+/**
+ * @brief Create a diffusion service with configuration
+ *
+ * Routes through service registry to find appropriate backend, honoring
+ * configuration hints such as preferred framework when provided.
+ *
+ * @param model_id Model identifier (registry ID or path to model)
+ * @param config Optional configuration (can be NULL)
+ * @param out_handle Output: Handle to the created service
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_create_with_config(const char* model_id,
+                                                      const rac_diffusion_config_t* config,
+                                                      rac_handle_t* out_handle);
+
+/**
+ * @brief Initialize a diffusion service
+ *
+ * @param handle Service handle
+ * @param model_path Path to the model directory
+ * @param config Configuration (can be NULL for defaults)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_initialize(rac_handle_t handle, const char* model_path,
+                                              const rac_diffusion_config_t* config);
+
+/**
+ * @brief Generate an image from prompt
+ *
+ * Blocking call that generates an image.
+ *
+ * @param handle Service handle
+ * @param options Generation options
+ * @param out_result Output: Generation result (caller must free with rac_diffusion_result_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_generate(rac_handle_t handle,
+                                            const rac_diffusion_options_t* options,
+                                            rac_diffusion_result_t* out_result);
+
+/**
+ * @brief Generate an image with progress reporting
+ *
+ * @param handle Service handle
+ * @param options Generation options
+ * @param progress_callback Callback for progress updates
+ * @param user_data User context passed to callback
+ * @param out_result Output: Generation result (caller must free with rac_diffusion_result_free)
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_generate_with_progress(
+    rac_handle_t handle, const rac_diffusion_options_t* options,
+    rac_diffusion_progress_callback_fn progress_callback, void* user_data,
+    rac_diffusion_result_t* out_result);
+
+/**
+ * @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_diffusion_get_info(rac_handle_t handle, rac_diffusion_info_t* out_info);
+
+/**
+ * @brief Get supported capabilities as bitmask
+ *
+ * @param handle Service handle
+ * @return Capability bitmask (RAC_DIFFUSION_CAP_* flags)
+ */
+RAC_API uint32_t rac_diffusion_get_capabilities(rac_handle_t handle);
+
+/**
+ * @brief Cancel ongoing generation
+ *
+ * @param handle Service handle
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_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_diffusion_cleanup(rac_handle_t handle);
+
+/**
+ * @brief Destroy a diffusion service instance
+ *
+ * @param handle Service handle to destroy
+ */
+RAC_API void rac_diffusion_destroy(rac_handle_t handle);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_DIFFUSION_SERVICE_H */

package/ios/Binaries/RACommons.xcframework/ios-arm64_x86_64-simulator/RACommons.framework/Headers/rac_diffusion_tokenizer.h

@@ -0,0 +1,167 @@
+/**
+ * @file rac_diffusion_tokenizer.h
+ * @brief RunAnywhere Commons - Diffusion Tokenizer Utilities
+ *
+ * Utilities for managing diffusion model tokenizer files.
+ * Apple's compiled CoreML models don't include tokenizer files (vocab.json, merges.txt),
+ * so they must be downloaded from HuggingFace.
+ *
+ * This API provides:
+ * - URL resolution for predefined tokenizer sources
+ * - Automatic download of missing tokenizer files
+ * - Support for custom tokenizer URLs
+ */
+
+#ifndef RAC_DIFFUSION_TOKENIZER_H
+#define RAC_DIFFUSION_TOKENIZER_H
+
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_diffusion_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// TOKENIZER FILE NAMES
+// =============================================================================
+
+/** Vocabulary file name */
+#define RAC_DIFFUSION_TOKENIZER_VOCAB_FILE "vocab.json"
+
+/** Merge rules file name */
+#define RAC_DIFFUSION_TOKENIZER_MERGES_FILE "merges.txt"
+
+// =============================================================================
+// URL RESOLUTION
+// =============================================================================
+
+/**
+ * @brief Get the base URL for a tokenizer source
+ *
+ * Returns the HuggingFace URL for the specified tokenizer source.
+ * For custom sources, returns the custom_base_url from config.
+ *
+ * @param source Tokenizer source preset
+ * @param custom_url Custom URL (only used when source == RAC_DIFFUSION_TOKENIZER_CUSTOM)
+ * @return Base URL string (static, do not free), or NULL if invalid
+ *
+ * @note URLs returned are HuggingFace raw file URLs (resolve/main/tokenizer)
+ *
+ * Example return values:
+ * - SD_1_5: "https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/tokenizer"
+ * - SD_2_X: "https://huggingface.co/stabilityai/stable-diffusion-2-1/resolve/main/tokenizer"
+ * - SDXL:   "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/tokenizer"
+ * - CUSTOM: Returns custom_url parameter
+ */
+RAC_API const char* rac_diffusion_tokenizer_get_base_url(rac_diffusion_tokenizer_source_t source,
+                                                         const char* custom_url);
+
+/**
+ * @brief Get the full URL for a tokenizer file
+ *
+ * Constructs the full URL for downloading a specific tokenizer file.
+ *
+ * @param source Tokenizer source preset
+ * @param custom_url Custom URL (only used when source == RAC_DIFFUSION_TOKENIZER_CUSTOM)
+ * @param filename File name to append (e.g., "vocab.json" or "merges.txt")
+ * @param out_url Output buffer for the full URL
+ * @param out_url_size Size of output buffer
+ * @return RAC_SUCCESS or error code
+ *
+ * Example:
+ * @code
+ * char url[512];
+ * rac_diffusion_tokenizer_get_file_url(
+ *     RAC_DIFFUSION_TOKENIZER_SD_1_5,
+ *     NULL,
+ *     "vocab.json",
+ *     url,
+ *     sizeof(url)
+ * );
+ * // url = "https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/tokenizer/vocab.json"
+ * @endcode
+ */
+RAC_API rac_result_t rac_diffusion_tokenizer_get_file_url(rac_diffusion_tokenizer_source_t source,
+                                                          const char* custom_url,
+                                                          const char* filename, char* out_url,
+                                                          size_t out_url_size);
+
+// =============================================================================
+// FILE MANAGEMENT
+// =============================================================================
+
+/**
+ * @brief Check if tokenizer files exist in a directory
+ *
+ * @param model_dir Path to the model directory
+ * @param out_has_vocab Output: true if vocab.json exists
+ * @param out_has_merges Output: true if merges.txt exists
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_tokenizer_check_files(const char* model_dir,
+                                                         rac_bool_t* out_has_vocab,
+                                                         rac_bool_t* out_has_merges);
+
+/**
+ * @brief Ensure tokenizer files exist, downloading if necessary
+ *
+ * Checks for vocab.json and merges.txt in the model directory.
+ * If missing and auto_download is enabled, downloads from the configured source.
+ *
+ * @param model_dir Path to the model directory
+ * @param config Tokenizer configuration (source, custom URL, auto_download)
+ * @return RAC_SUCCESS if files exist or were downloaded successfully
+ *         RAC_ERROR_FILE_NOT_FOUND if files missing and auto_download disabled
+ *         RAC_ERROR_NETWORK if download failed
+ *
+ * Example:
+ * @code
+ * rac_diffusion_tokenizer_config_t config = {
+ *     .source = RAC_DIFFUSION_TOKENIZER_SD_1_5,
+ *     .custom_base_url = NULL,
+ *     .auto_download = RAC_TRUE
+ * };
+ * rac_result_t result = rac_diffusion_tokenizer_ensure_files("/path/to/model", &config);
+ * @endcode
+ */
+RAC_API rac_result_t
+rac_diffusion_tokenizer_ensure_files(const char* model_dir,
+                                     const rac_diffusion_tokenizer_config_t* config);
+
+/**
+ * @brief Download a tokenizer file
+ *
+ * Downloads a specific tokenizer file from the configured source.
+ *
+ * @param source Tokenizer source preset
+ * @param custom_url Custom URL (only used when source == RAC_DIFFUSION_TOKENIZER_CUSTOM)
+ * @param filename File name to download (e.g., "vocab.json")
+ * @param output_path Full path where the file should be saved
+ * @return RAC_SUCCESS or error code
+ */
+RAC_API rac_result_t rac_diffusion_tokenizer_download_file(rac_diffusion_tokenizer_source_t source,
+                                                           const char* custom_url,
+                                                           const char* filename,
+                                                           const char* output_path);
+
+// =============================================================================
+// DEFAULT TOKENIZER SOURCE FOR MODEL VARIANT
+// =============================================================================
+
+/**
+ * @brief Get the default tokenizer source for a model variant
+ *
+ * Returns the recommended tokenizer source for a given model variant.
+ *
+ * @param model_variant Model variant (SD 1.5, SD 2.1, SDXL, etc.)
+ * @return Default tokenizer source
+ */
+RAC_API rac_diffusion_tokenizer_source_t
+rac_diffusion_tokenizer_default_for_variant(rac_diffusion_model_variant_t model_variant);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_DIFFUSION_TOKENIZER_H */