@runanywhere/core 0.17.7 → 0.18.0

package/ios/Binaries/RACommons.xcframework/ios-arm64/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/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 */