libembedding-ng 1.0.1__py3-none-win_amd64.whl

libembedding/__init__.py

@@ -0,0 +1,48 @@
+"""libembedding — Fast ONNX-based text, image, and sparse embeddings for Python."""
+
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    __version__ = version("libembedding-ng")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+from .text_embedding import TextEmbedding
+from .sparse_text_embedding import SparseTextEmbedding
+from .image_embedding import ImageEmbedding
+from .reranker import Reranker
+from .types import SparseEmbedding, RerankResult, ModelInfo, ModelDesc, Stats
+from .models import (
+    list_text_models,
+    list_sparse_models,
+    list_image_models,
+    list_reranker_models,
+)
+from .similarity import cosine_similarity, dot_product, euclidean_distance
+from .exceptions import LembedError
+
+# Version from C API (runtime)
+try:
+    from ._binding import lib
+    __version__ = lib.lembed_version().decode("utf-8", errors="replace")
+except Exception:
+    pass  # fall back to importlib.metadata version above
+
+__all__ = [
+    "TextEmbedding",
+    "SparseTextEmbedding",
+    "ImageEmbedding",
+    "Reranker",
+    "SparseEmbedding",
+    "RerankResult",
+    "ModelInfo",
+    "ModelDesc",
+    "Stats",
+    "list_text_models",
+    "list_sparse_models",
+    "list_image_models",
+    "list_reranker_models",
+    "cosine_similarity",
+    "dot_product",
+    "euclidean_distance",
+    "LembedError",
+]

libembedding/_binding.py

@@ -0,0 +1,31 @@
+"""Low-level cffi binding layer. Loads the shared library and exposes ffi/lib."""
+
+import cffi
+import platform
+from pathlib import Path
+
+ffi = cffi.FFI()
+
+_cdefs_path = Path(__file__).with_name("_cdefs.h")
+ffi.cdef(_cdefs_path.read_text())
+
+
+def _find_library() -> str:
+    ext = {"Darwin": ".dylib", "Linux": ".so", "Windows": ".dll"}.get(
+        platform.system(), ".so"
+    )
+    pkg_dir = Path(__file__).parent
+    candidates = [
+        pkg_dir / f"libembedding{ext}",
+        pkg_dir / f"lib" / f"libembedding{ext}",
+        # Development: look in build directory relative to project root
+        pkg_dir.parent.parent.parent.parent / "build" / f"python" / f"libembedding{ext}",
+        pkg_dir.parent.parent.parent.parent / "build" / f"libembedding{ext}",
+    ]
+    for c in candidates:
+        if c.exists():
+            return str(c)
+    return f"libembedding{ext}"
+
+
+lib = ffi.dlopen(_find_library())

libembedding/_cdefs.h

@@ -0,0 +1,319 @@
+/* Flattened C declarations for cffi — derived from libembedding public headers.
+ * No preprocessor directives, no C++ constructs. */
+
+/* ── Error handling ─────────────────────────────────────────────── */
+
+typedef enum {
+    LEMBED_OK = 0,
+    LEMBED_ERROR_INVALID_ARGUMENT,
+    LEMBED_ERROR_OUT_OF_MEMORY,
+    LEMBED_ERROR_ONNX_RUNTIME,
+    LEMBED_ERROR_TOKENIZER,
+    LEMBED_ERROR_DOWNLOAD,
+    LEMBED_ERROR_IO,
+    LEMBED_ERROR_MODEL_NOT_FOUND,
+    LEMBED_ERROR_UNSUPPORTED,
+    LEMBED_ERROR_BATCH_SIZE,
+} lembed_status_t;
+
+const char* lembed_status_message(lembed_status_t status);
+const char* lembed_last_error(void);
+const char* lembed_version(void);
+
+/* ── Enums ──────────────────────────────────────────────────────── */
+
+typedef enum {
+    LEMBED_PROVIDER_CPU = 0,
+    LEMBED_PROVIDER_CUDA,
+    LEMBED_PROVIDER_COREML,
+    LEMBED_PROVIDER_DIRECTML,
+    LEMBED_PROVIDER_TENSORRT,
+} lembed_execution_provider_t;
+
+typedef enum {
+    LEMBED_POOLING_CLS = 0,
+    LEMBED_POOLING_MEAN,
+} lembed_pooling_t;
+
+typedef enum {
+    LEMBED_QUANTIZATION_NONE = 0,
+    LEMBED_QUANTIZATION_STATIC,
+    LEMBED_QUANTIZATION_DYNAMIC,
+} lembed_quantization_t;
+
+typedef enum {
+    LEMBED_TEXT_ALL_MINILM_L6_V2 = 0,
+    LEMBED_TEXT_ALL_MINILM_L6_V2_Q,
+    LEMBED_TEXT_ALL_MINILM_L12_V2,
+    LEMBED_TEXT_ALL_MINILM_L12_V2_Q,
+    LEMBED_TEXT_ALL_MPNET_BASE_V2,
+    LEMBED_TEXT_BGE_BASE_EN_V15,
+    LEMBED_TEXT_BGE_BASE_EN_V15_Q,
+    LEMBED_TEXT_BGE_LARGE_EN_V15,
+    LEMBED_TEXT_BGE_LARGE_EN_V15_Q,
+    LEMBED_TEXT_BGE_SMALL_EN_V15,
+    LEMBED_TEXT_BGE_SMALL_EN_V15_Q,
+    LEMBED_TEXT_NOMIC_EMBED_TEXT_V1,
+    LEMBED_TEXT_NOMIC_EMBED_TEXT_V15,
+    LEMBED_TEXT_NOMIC_EMBED_TEXT_V15_Q,
+    LEMBED_TEXT_PARAPHRASE_ML_MINILM_L12_V2,
+    LEMBED_TEXT_PARAPHRASE_ML_MINILM_L12_V2_Q,
+    LEMBED_TEXT_PARAPHRASE_ML_MPNET_BASE_V2,
+    LEMBED_TEXT_BGE_SMALL_ZH_V15,
+    LEMBED_TEXT_BGE_LARGE_ZH_V15,
+    LEMBED_TEXT_BGE_M3,
+    LEMBED_TEXT_MODERNBERT_EMBED_LARGE,
+    LEMBED_TEXT_MULTILINGUAL_E5_SMALL,
+    LEMBED_TEXT_MULTILINGUAL_E5_BASE,
+    LEMBED_TEXT_MULTILINGUAL_E5_LARGE,
+    LEMBED_TEXT_MXBAI_EMBED_LARGE_V1,
+    LEMBED_TEXT_MXBAI_EMBED_LARGE_V1_Q,
+    LEMBED_TEXT_GTE_BASE_EN_V15,
+    LEMBED_TEXT_GTE_BASE_EN_V15_Q,
+    LEMBED_TEXT_GTE_LARGE_EN_V15,
+    LEMBED_TEXT_GTE_LARGE_EN_V15_Q,
+    LEMBED_TEXT_CLIP_VIT_B32,
+    LEMBED_TEXT_JINA_EMBEDDINGS_V2_BASE_CODE,
+    LEMBED_TEXT_JINA_EMBEDDINGS_V2_BASE_EN,
+    LEMBED_TEXT_EMBEDDING_GEMMA_300M,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_XS,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_XS_Q,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_S,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_S_Q,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_M,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_M_Q,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_M_LONG,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_M_LONG_Q,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_L,
+    LEMBED_TEXT_SNOWFLAKE_ARCTIC_EMBED_L_Q,
+    LEMBED_TEXT_MODEL_COUNT,
+} lembed_text_model_t;
+
+typedef enum {
+    LEMBED_SPARSE_SPLADE_PP_V1 = 0,
+    LEMBED_SPARSE_BGE_M3,
+    LEMBED_SPARSE_MODEL_COUNT,
+} lembed_sparse_model_t;
+
+typedef enum {
+    LEMBED_IMAGE_CLIP_VIT_B32 = 0,
+    LEMBED_IMAGE_RESNET50,
+    LEMBED_IMAGE_UNICOM_VIT_B16,
+    LEMBED_IMAGE_UNICOM_VIT_B32,
+    LEMBED_IMAGE_NOMIC_EMBED_VISION_V15,
+    LEMBED_IMAGE_MODEL_COUNT,
+} lembed_image_model_t;
+
+typedef enum {
+    LEMBED_RERANKER_BGE_BASE = 0,
+    LEMBED_RERANKER_BGE_V2_M3,
+    LEMBED_RERANKER_JINA_V1_TURBO_EN,
+    LEMBED_RERANKER_JINA_V2_BASE_MULTILINGUAL,
+    LEMBED_RERANKER_MODEL_COUNT,
+} lembed_reranker_model_t;
+
+/* ── Structs ────────────────────────────────────────────────────── */
+
+typedef struct {
+    const char* model_name;
+    const char* model_code;
+    const char* model_file;
+    const char* description;
+    int         dim;
+    int         max_tokens;
+    int         pooling;
+    int         quantization;
+} lembed_model_info_t;
+
+typedef struct {
+    const char*                name;
+    int                        dimension;
+    int                        max_length;
+    int                        pooling;
+    int                        num_threads;
+    int                        batch_size;
+    lembed_execution_provider_t provider;
+    int                        device_id;
+} lembed_model_desc_t;
+
+typedef struct {
+    unsigned long long texts_embedded;
+    unsigned long long batches_run;
+    double avg_latency_ms;
+} lembed_stats_t;
+
+typedef struct lembed_text_embedding    lembed_text_embedding_t;
+typedef struct lembed_sparse_embedding  lembed_sparse_embedding_ctx_t;
+typedef struct lembed_image_embedding   lembed_image_embedding_t;
+typedef struct lembed_reranker          lembed_reranker_t;
+
+typedef struct {
+    float*  data;
+    int     num_embeddings;
+    int     dim;
+} lembed_embeddings_t;
+
+typedef struct {
+    int32_t* indices;
+    float*   values;
+    int      length;
+} lembed_sparse_embedding_t;
+
+typedef struct {
+    lembed_sparse_embedding_t* items;
+    int count;
+} lembed_sparse_embeddings_t;
+
+typedef struct {
+    int   index;
+    float score;
+} lembed_rerank_result_t;
+
+typedef struct {
+    lembed_rerank_result_t* items;
+    int count;
+} lembed_rerank_results_t;
+
+typedef struct {
+    lembed_text_model_t         model;
+    lembed_execution_provider_t provider;
+    int                         device_id;
+    const char*                 cache_dir;
+    int                         max_length;
+    int                         num_threads;
+    int                         show_download_progress;
+    int                         batch_size;
+    int                         offline;
+    int                         pooling;
+    int                         dim;
+} lembed_text_options_t;
+
+typedef struct {
+    lembed_sparse_model_t       model;
+    lembed_execution_provider_t provider;
+    int                         device_id;
+    const char*                 cache_dir;
+    int                         max_length;
+    int                         num_threads;
+    int                         show_download_progress;
+    int                         batch_size;
+    int                         offline;
+} lembed_sparse_options_t;
+
+typedef struct {
+    lembed_image_model_t        model;
+    lembed_execution_provider_t provider;
+    int                         device_id;
+    const char*                 cache_dir;
+    int                         num_threads;
+    int                         show_download_progress;
+    int                         batch_size;
+    int                         offline;
+    int                         dim;
+} lembed_image_options_t;
+
+typedef struct {
+    lembed_reranker_model_t     model;
+    lembed_execution_provider_t provider;
+    int                         device_id;
+    const char*                 cache_dir;
+    int                         max_length;
+    int                         num_threads;
+    int                         show_download_progress;
+    int                         batch_size;
+    int                         offline;
+} lembed_reranker_options_t;
+
+typedef struct {
+    const unsigned char* onnx_data;
+    size_t               onnx_data_size;
+    const unsigned char* tokenizer_json;
+    size_t               tokenizer_json_size;
+    const unsigned char* config_json;
+    size_t               config_json_size;
+    lembed_pooling_t     pooling;
+    int                  dim;
+    int                  max_length;
+} lembed_user_defined_model_t;
+
+/* ── Functions ──────────────────────────────────────────────────── */
+
+/* Options defaults */
+lembed_text_options_t    lembed_text_options_default(void);
+lembed_sparse_options_t  lembed_sparse_options_default(void);
+lembed_image_options_t   lembed_image_options_default(void);
+lembed_reranker_options_t lembed_reranker_options_default(void);
+
+/* Text embedding */
+lembed_status_t lembed_text_embedding_create(const lembed_text_options_t* options, lembed_text_embedding_t** out);
+lembed_status_t lembed_text_embedding_create_custom(const lembed_user_defined_model_t* model, lembed_execution_provider_t provider, int num_threads, lembed_text_embedding_t** out);
+lembed_status_t lembed_text_embedding_create_from_path(const char* dir_path, const lembed_text_options_t* options, lembed_text_embedding_t** out);
+lembed_status_t lembed_text_embedding_embed(lembed_text_embedding_t* ctx, const char* const* texts, int num_texts, int batch_size, lembed_embeddings_t* result);
+lembed_status_t lembed_text_embedding_embed_stream(lembed_text_embedding_t* ctx, const char* const* texts, int num_texts, int batch_size, void (*callback)(const float* embedding, int dim, void* userdata), void* userdata);
+int lembed_text_embedding_dim(const lembed_text_embedding_t* ctx);
+const lembed_model_desc_t* lembed_text_embedding_desc(const lembed_text_embedding_t* ctx);
+const char* lembed_text_embedding_model_name(const lembed_text_embedding_t* ctx);
+int lembed_text_embedding_max_length(const lembed_text_embedding_t* ctx);
+void lembed_text_embedding_stats(const lembed_text_embedding_t* ctx, lembed_stats_t* out);
+void lembed_text_embedding_free(lembed_text_embedding_t* ctx);
+
+/* Sparse text embedding */
+lembed_status_t lembed_sparse_text_embedding_create(const lembed_sparse_options_t* options, lembed_sparse_embedding_ctx_t** out);
+lembed_status_t lembed_sparse_text_embedding_create_from_path(const char* dir_path, const lembed_sparse_options_t* options, lembed_sparse_embedding_ctx_t** out);
+lembed_status_t lembed_sparse_text_embedding_embed(lembed_sparse_embedding_ctx_t* ctx, const char* const* texts, int num_texts, int batch_size, lembed_sparse_embeddings_t* result);
+const lembed_model_desc_t* lembed_sparse_text_embedding_desc(const lembed_sparse_embedding_ctx_t* ctx);
+const char* lembed_sparse_text_embedding_model_name(const lembed_sparse_embedding_ctx_t* ctx);
+int lembed_sparse_text_embedding_max_length(const lembed_sparse_embedding_ctx_t* ctx);
+void lembed_sparse_text_embedding_stats(const lembed_sparse_embedding_ctx_t* ctx, lembed_stats_t* out);
+void lembed_sparse_text_embedding_free(lembed_sparse_embedding_ctx_t* ctx);
+
+/* Image embedding */
+lembed_status_t lembed_image_embedding_create(const lembed_image_options_t* options, lembed_image_embedding_t** out);
+lembed_status_t lembed_image_embedding_create_from_path(const char* dir_path, const lembed_image_options_t* options, lembed_image_embedding_t** out);
+lembed_status_t lembed_image_embedding_embed_files(lembed_image_embedding_t* ctx, const char* const* file_paths, int num_images, int batch_size, lembed_embeddings_t* result);
+lembed_status_t lembed_image_embedding_embed_bytes(lembed_image_embedding_t* ctx, const unsigned char* const* image_data, const int* image_sizes, int num_images, int batch_size, lembed_embeddings_t* result);
+int lembed_image_embedding_dim(const lembed_image_embedding_t* ctx);
+const lembed_model_desc_t* lembed_image_embedding_desc(const lembed_image_embedding_t* ctx);
+const char* lembed_image_embedding_model_name(const lembed_image_embedding_t* ctx);
+int lembed_image_embedding_max_length(const lembed_image_embedding_t* ctx);
+void lembed_image_embedding_stats(const lembed_image_embedding_t* ctx, lembed_stats_t* out);
+void lembed_image_embedding_free(lembed_image_embedding_t* ctx);
+
+/* Reranker */
+lembed_status_t lembed_reranker_create(const lembed_reranker_options_t* options, lembed_reranker_t** out);
+lembed_status_t lembed_reranker_create_from_path(const char* dir_path, const lembed_reranker_options_t* options, lembed_reranker_t** out);
+lembed_status_t lembed_reranker_rerank(lembed_reranker_t* ctx, const char* query, const char* const* documents, int num_documents, int batch_size, lembed_rerank_results_t* result);
+const lembed_model_desc_t* lembed_reranker_desc(const lembed_reranker_t* ctx);
+const char* lembed_reranker_model_name(const lembed_reranker_t* ctx);
+int lembed_reranker_max_length(const lembed_reranker_t* ctx);
+void lembed_reranker_stats(const lembed_reranker_t* ctx, lembed_stats_t* out);
+void lembed_reranker_free(lembed_reranker_t* ctx);
+
+/* Model registry */
+lembed_status_t lembed_get_text_model_info(lembed_text_model_t model, lembed_model_info_t* out);
+lembed_status_t lembed_get_sparse_model_info(lembed_sparse_model_t model, lembed_model_info_t* out);
+lembed_status_t lembed_get_image_model_info(lembed_image_model_t model, lembed_model_info_t* out);
+lembed_status_t lembed_get_reranker_model_info(lembed_reranker_model_t model, lembed_model_info_t* out);
+lembed_status_t lembed_list_text_models(const lembed_model_info_t** out, int* count);
+lembed_status_t lembed_list_sparse_models(const lembed_model_info_t** out, int* count);
+lembed_status_t lembed_list_image_models(const lembed_model_info_t** out, int* count);
+lembed_status_t lembed_list_reranker_models(const lembed_model_info_t** out, int* count);
+int lembed_find_text_model_by_code(const char* model_code);
+int lembed_find_sparse_model_by_code(const char* model_code);
+
+/* Downloader */
+lembed_status_t lembed_ensure_text_model(lembed_text_model_t model, const char* cache_dir, int show_progress, int offline, char** model_dir_out);
+lembed_status_t lembed_ensure_sparse_model(lembed_sparse_model_t model, const char* cache_dir, int show_progress, int offline, char** model_dir_out);
+lembed_status_t lembed_ensure_image_model(lembed_image_model_t model, const char* cache_dir, int show_progress, int offline, char** model_dir_out);
+lembed_status_t lembed_ensure_reranker_model(lembed_reranker_model_t model, const char* cache_dir, int show_progress, int offline, char** model_dir_out);
+void lembed_free_string(char* s);
+
+/* Similarity */
+float lembed_cosine_similarity(const float* a, const float* b, int dim);
+float lembed_dot_product(const float* a, const float* b, int dim);
+float lembed_euclidean_distance(const float* a, const float* b, int dim);
+
+/* Memory free */
+void lembed_embeddings_free(lembed_embeddings_t* result);
+void lembed_sparse_embeddings_free(lembed_sparse_embeddings_t* result);
+void lembed_rerank_results_free(lembed_rerank_results_t* result);

libembedding/_status.py

@@ -0,0 +1,36 @@
+"""Status code checking — raises Python exceptions from C status codes."""
+
+from ._binding import ffi, lib
+from .exceptions import (
+    LembedError,
+    InvalidArgumentError,
+    OutOfMemoryError,
+    OnnxRuntimeError,
+    TokenizerError,
+    DownloadError,
+    IOError,
+    ModelNotFoundError,
+    UnsupportedError,
+    BatchSizeError,
+)
+
+_STATUS_MAP = {
+    1: InvalidArgumentError,
+    2: OutOfMemoryError,
+    3: OnnxRuntimeError,
+    4: TokenizerError,
+    5: DownloadError,
+    6: IOError,
+    7: ModelNotFoundError,
+    8: UnsupportedError,
+    9: BatchSizeError,
+}
+
+
+def check_status(status: int) -> None:
+    if status == 0:
+        return
+    msg = ffi.string(lib.lembed_status_message(status)).decode("utf-8", errors="replace")
+    detail = ffi.string(lib.lembed_last_error()).decode("utf-8", errors="replace")
+    exc_cls = _STATUS_MAP.get(status, LembedError)
+    raise exc_cls(status, msg, detail)

libembedding/exceptions.py

@@ -0,0 +1,47 @@
+"""Exception hierarchy mapped from lembed_status_t."""
+
+
+class LembedError(Exception):
+    """Base exception for libembedding errors."""
+
+    def __init__(self, status_code: int, message: str, detail: str = ""):
+        self.status_code = status_code
+        self.message = message
+        self.detail = detail
+        super().__init__(f"{message}: {detail}" if detail else message)
+
+
+class InvalidArgumentError(LembedError):
+    pass
+
+
+class OutOfMemoryError(LembedError):
+    pass
+
+
+class OnnxRuntimeError(LembedError):
+    pass
+
+
+class TokenizerError(LembedError):
+    pass
+
+
+class DownloadError(LembedError):
+    pass
+
+
+class IOError(LembedError):
+    pass
+
+
+class ModelNotFoundError(LembedError):
+    pass
+
+
+class UnsupportedError(LembedError):
+    pass
+
+
+class BatchSizeError(LembedError):
+    pass

libembedding/image_embedding.py

@@ -0,0 +1,197 @@
+"""High-level image embedding API."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+from ._binding import ffi, lib
+from ._status import check_status
+from .models import (
+    resolve_image_model,
+    list_image_models,
+    _PROVIDER_MAP,
+    _desc_from_c,
+    _is_local_path,
+)
+from .types import ModelDesc, Stats
+from .exceptions import ModelNotFoundError
+
+
+class ImageEmbedding:
+    """Generate dense vector embeddings from images.
+
+    Args:
+        model_name: Model name (e.g. "openai/clip-vit-base-patch32") or local
+            directory path.
+        provider: Execution provider.
+        cache_dir: Model cache directory.
+        threads: Number of threads (0 = auto).
+        batch_size: Internal batch size (default 32).
+        offline: If True, use cached models only (default False).
+        show_download_progress: Show download progress bar.
+        dim: Output dimension for local models without config.json (0 = auto).
+        num_threads: Deprecated; use ``threads``.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "Qdrant/clip-ViT-B-32-vision",
+        *,
+        provider: str = "cpu",
+        device_id: int = 0,
+        cache_dir: str | None = None,
+        threads: int = 0,
+        batch_size: int = 30,
+        offline: bool = False,
+        show_download_progress: bool = True,
+        dim: int = 0,
+        num_threads: int | None = None,
+    ):
+        if num_threads is not None:
+            warnings.warn(
+                "num_threads is deprecated, use threads",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            threads = num_threads
+
+        opts = lib.lembed_image_options_default()
+        opts.provider = _PROVIDER_MAP[provider.lower()]
+        opts.device_id = device_id
+        self._cache_dir_buf = (
+            ffi.new("char[]", cache_dir.encode("utf-8")) if cache_dir else ffi.NULL
+        )
+        opts.cache_dir = self._cache_dir_buf
+        opts.num_threads = threads
+        opts.batch_size = batch_size
+        opts.offline = int(offline)
+        opts.show_download_progress = int(show_download_progress)
+        opts.dim = dim
+
+        ctx_ptr = ffi.new("lembed_image_embedding_t **")
+
+        try:
+            model_idx = resolve_image_model(model_name)
+            opts.model = model_idx
+            check_status(lib.lembed_image_embedding_create(
+                ffi.addressof(opts), ctx_ptr))
+        except ModelNotFoundError:
+            if _is_local_path(model_name):
+                check_status(lib.lembed_image_embedding_create_from_path(
+                    model_name.encode("utf-8"), ffi.addressof(opts), ctx_ptr))
+            else:
+                raise
+
+        self._ctx = ffi.gc(ctx_ptr[0], lib.lembed_image_embedding_free)
+        self._dim = lib.lembed_image_embedding_dim(self._ctx)
+        self._batch_size = batch_size
+
+    @staticmethod
+    def list_supported_models():
+        """Return a list of all supported image embedding models."""
+        return list_image_models()
+
+    @property
+    def dim(self) -> int:
+        return self._dim
+
+    @property
+    def batch_size(self) -> int:
+        """Configured internal batch size."""
+        return self._batch_size
+
+    def info(self) -> ModelDesc:
+        """Return runtime model descriptor."""
+        desc_ptr = lib.lembed_image_embedding_desc(self._ctx)
+        return _desc_from_c(desc_ptr)
+
+    @property
+    def name(self) -> str:
+        """Model name or local path."""
+        name_ptr = lib.lembed_image_embedding_model_name(self._ctx)
+        return ffi.string(name_ptr).decode("utf-8", errors="replace") if name_ptr else ""
+
+    def embed_files(self, paths: list[str], *, batch_size: int | None = None) -> np.ndarray:
+        """Embed images from file paths.
+
+        Returns:
+            numpy array of shape (len(paths), dim) with dtype float32.
+        """
+        n = len(paths)
+        if n == 0:
+            return np.empty((0, self._dim), dtype=np.float32)
+
+        bs = 0 if batch_size is None else batch_size
+
+        encoded = [p.encode("utf-8") for p in paths]
+        c_strs = [ffi.new("char[]", e) for e in encoded]
+        c_paths = ffi.new("char*[]", c_strs)
+
+        result = ffi.new("lembed_embeddings_t *")
+        check_status(
+            lib.lembed_image_embedding_embed_files(self._ctx, c_paths, n, bs, result)
+        )
+
+        try:
+            buf = ffi.buffer(result.data, result.num_embeddings * result.dim * 4)
+            arr = np.frombuffer(buf, dtype=np.float32).copy()
+            return arr.reshape(result.num_embeddings, result.dim)
+        finally:
+            lib.lembed_embeddings_free(result)
+
+    def embed_bytes(self, images: list[bytes], *, batch_size: int | None = None) -> np.ndarray:
+        """Embed images from raw bytes (JPEG, PNG, etc.).
+
+        Returns:
+            numpy array of shape (len(images), dim) with dtype float32.
+        """
+        n = len(images)
+        if n == 0:
+            return np.empty((0, self._dim), dtype=np.float32)
+
+        bs = 0 if batch_size is None else batch_size
+
+        c_data = ffi.new("unsigned char*[]", n)
+        c_sizes = ffi.new("int[]", n)
+        kept = []
+        for i, img in enumerate(images):
+            buf = ffi.new("unsigned char[]", img)
+            kept.append(buf)
+            c_data[i] = buf
+            c_sizes[i] = len(img)
+
+        result = ffi.new("lembed_embeddings_t *")
+        check_status(
+            lib.lembed_image_embedding_embed_bytes(
+                self._ctx, c_data, c_sizes, n, bs, result
+            )
+        )
+
+        try:
+            buf = ffi.buffer(result.data, result.num_embeddings * result.dim * 4)
+            arr = np.frombuffer(buf, dtype=np.float32).copy()
+            return arr.reshape(result.num_embeddings, result.dim)
+        finally:
+            lib.lembed_embeddings_free(result)
+
+    def stats(self) -> Stats:
+        """Return runtime usage statistics."""
+        s = ffi.new("lembed_stats_t *")
+        lib.lembed_image_embedding_stats(self._ctx, s)
+        return Stats(
+            texts_embedded=s.texts_embedded,
+            batches_run=s.batches_run,
+            avg_latency_ms=s.avg_latency_ms,
+        )
+
+    def close(self) -> None:
+        """Release the underlying C resources."""
+        self._ctx = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()