optimum-rbln 0.9.3.post1__py3-none-any.whl

optimum/rbln/utils/model_utils.py

@@ -0,0 +1,63 @@
+# Copyright 2025 Rebellions Inc. All rights reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import importlib
+from typing import TYPE_CHECKING, Type
+
+
+if TYPE_CHECKING:
+    from ..modeling import RBLNModel
+
+# Prefix used for RBLN model class names
+RBLN_PREFIX = "RBLN"
+
+
+MODEL_MAPPING = {}
+
+
+def convert_hf_to_rbln_model_name(hf_model_name: str):
+    """
+    Convert HuggingFace model name to RBLN model name.
+
+    Args:
+        hf_model_name (str): The HuggingFace model name.
+
+    Returns:
+        str: The corresponding RBLN model name.
+    """
+    return RBLN_PREFIX + hf_model_name
+
+
+def convert_rbln_to_hf_model_name(rbln_model_name: str):
+    """
+    Convert RBLN model name to HuggingFace model name.
+
+    Args:
+        rbln_model_name (str): The RBLN model name.
+
+    Returns:
+        str: The corresponding HuggingFace model name.
+    """
+
+    return rbln_model_name.removeprefix(RBLN_PREFIX)
+
+
+def get_rbln_model_cls(cls_name: str) -> Type["RBLNModel"]:
+    cls = getattr(importlib.import_module("optimum.rbln"), cls_name, None)
+    if cls is None:
+        if cls_name in MODEL_MAPPING:
+            cls = MODEL_MAPPING[cls_name]
+        else:
+            raise AttributeError(f"RBLNModel for {cls_name} not found.")
+    return cls

optimum/rbln/utils/runtime_utils.py

@@ -0,0 +1,249 @@
+# Copyright 2025 Rebellions Inc. All rights reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+import threading
+from typing import Any, List, Optional, Union
+
+import rebel
+import torch
+
+
+def get_available_dram(npu: Optional[str] = None) -> int:
+    """
+    Get the available DRAM size of the specified NPU.
+
+    Args:
+        npu : Optional[str], default=None
+            The NPU to get the available DRAM size.
+            If None, the function will attempt to retrieve through `ensure_valid_npu()`
+
+    Returns:
+        int
+            The available DRAM size in bytes.
+    """
+    if npu is None:
+        if not rebel.npu_is_available(0):
+            raise RuntimeError("No NPU is available to get available DRAM size.")
+
+        npu = rebel.get_npu_name(0)
+
+    if npu.startswith("RBLN-CR"):
+        # TODO(jongho): Assuming 4 chiplets.
+        DRAM_NBYTES = 144 * 2**30
+        SYS_DRAM_NBYTES = 4 * 2**30
+    elif npu.startswith("RBLN-CA"):
+        DRAM_NBYTES = 16 * 2**30
+        SYS_DRAM_NBYTES = 288 * 2**20
+    else:
+        raise ValueError(f"Unknown npu name: {npu}")
+
+    return DRAM_NBYTES - SYS_DRAM_NBYTES
+
+
+def normalize_npu(npu: str) -> str:
+    """Normalize the NPU string by removing the form factor."""
+    match = re.match(r"(RBLN-CA|RBLN-CR)(\d+)", npu)
+    if match:
+        prefix, num = match.groups()
+        if len(num) == 1:
+            # Convert "RBLN-CAx" → "RBLN-CA0"
+            # (e.g., "RBLN-CA2" -> "RBLN-CA0")
+            npu = f"{prefix}0"
+        elif len(num) == 2:
+            # Strip form factor (e.g., "RBLN-CA15" → "RBLN-CA1")
+            npu = f"{prefix}{num[:-1]}"
+    return npu
+
+
+def tp_and_devices_are_ok(
+    tensor_parallel_size: Optional[int] = None,
+    device: Optional[Union[int, List[int]]] = None,
+    npu: Optional[str] = None,
+) -> Optional[str]:
+    if tensor_parallel_size is None:
+        tensor_parallel_size = 1
+
+    if rebel.device_count() < tensor_parallel_size:
+        return (
+            f"Tensor parallel size {tensor_parallel_size} is greater than "
+            f"the number of available devices {rebel.device_count()}."
+        )
+
+    if device is None:
+        device = list(range(tensor_parallel_size))
+    elif isinstance(device, int):
+        device = [device]
+    elif isinstance(device, list):
+        if any(not isinstance(d, int) for d in device):
+            return "Device must be a(n) (list of) integer(s)."
+        if len(device) != tensor_parallel_size:
+            return (
+                f"The number of devices ({len(device)}) does not match tensor parallel size ({tensor_parallel_size})."
+            )
+    else:
+        return f"Invalid device: {device}"
+
+    for device_id in device:
+        if device_id < 0:  # if any device is dummy device, skip it
+            return None
+        if rebel.get_npu_name(device_id) is None:
+            return (
+                f"Device {device_id} is not a valid NPU device. Please check your NPU status with 'rbln-stat' command."
+            )
+
+    if npu is not None:
+        for device_id in device:
+            npu_name = rebel.get_npu_name(device_id)
+            if normalize_npu(npu_name) != normalize_npu(npu):
+                return f"Device {device_id} ({npu_name}) is not on the same NPU as {npu}."
+
+    return None
+
+
+class RBLNPytorchRuntime:
+    mandatory_members = []
+
+    def __init__(self, runtime: rebel.Runtime, **kwargs) -> None:
+        self.runtime = runtime
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+        for mandatory_member in self.mandatory_members:
+            if mandatory_member not in kwargs:
+                raise AttributeError(f"`{mandatory_member}` should be assigned to {self.__class__.__name__} objects.")
+
+    def __call__(self, *args: Any, **kwds: Any) -> Any:
+        return self.forward(*args, **kwds)
+
+    def forward(self, *args: List["torch.Tensor"], **kwargs: "torch.Tensor"):
+        # filtering useless args or kwarg such as None.
+        args = list(filter(lambda arg: isinstance(arg, torch.Tensor), args))
+        kwargs = dict(filter(lambda kwarg: isinstance(kwarg[1], torch.Tensor) or kwarg[0] == "out", kwargs.items()))
+        output = self.runtime(*args, **kwargs)
+        return output
+
+    def __repr__(self) -> str:
+        return repr(self.runtime)
+
+    def parameters(self):
+        yield torch.tensor([1.0], dtype=torch.float32, device=torch.device("cpu"))
+
+
+class UnavailableRuntime:
+    """
+    A placeholder class used when model runtimes are not created.
+
+    This class is returned by RBLNBaseModel._from_compiled_models when rbln_config.create_runtimes=False.
+    It provides proper error messages when users attempt to use a model that was loaded without
+    runtime creation.
+
+    Usage:
+        1. When compiling models on machines without NPU hardware
+        2. When preparing models for later deployment
+        3. When only model compilation is needed, not inference
+
+    To use a model with runtimes, either:
+        - Load the model with from_pretrained(..., rbln_create_runtimes=True)
+        - Or set rbln_config={"create_runtimes": True} during loading
+    """
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Raises a RuntimeError when the model is called without runtimes."""
+        raise self.forward(*args, **kwargs)
+
+    def __len__(self) -> int:
+        """Returns 0 since no runtimes are available."""
+        return 0
+
+    def __getitem__(self, idx: int) -> Any:
+        """Returns self for any index, allowing iteration to work with appropriate errors."""
+        return self
+
+    def __iter__(self):
+        """Returns an iterator with self as the only item."""
+        return iter([self])
+
+    def forward(self, *args: List["torch.Tensor"], **kwargs: "torch.Tensor"):
+        """Raises a detailed RuntimeError explaining why inference cannot be performed."""
+        raise RuntimeError(
+            "Cannot perform inference: RBLN runtime is not available.\n\n"
+            "This model was loaded with create_runtimes=False. To use this model for inference:\n"
+            "1. Load the model with runtime creation enabled:\n"
+            "   model = RBLNModel.from_pretrained(..., rbln_create_runtimes=True)\n"
+            "2. Ensure your NPU hardware is properly configured (check with 'rbln-stat' command)\n"
+            "3. If you're on a machine without NPU hardware, you need to transfer the model files\n"
+            "   to a compatible system with NPU support."
+        )
+
+    def __repr__(self) -> str:
+        """Returns a detailed string representation of the UnavailableRuntime."""
+        return "<UnavailableRuntime: Model loaded without runtime creation (create_runtimes=False)>"
+
+
+class ContextRblnConfig:
+    _local = threading.local()
+
+    def __init__(
+        self,
+        device=None,
+        device_map=None,
+        create_runtimes=None,
+        activate_profiler=None,
+        timeout=None,
+    ):
+        self.device = device
+        self.device_map = device_map
+        self.create_runtimes = create_runtimes
+        self.activate_profiler = activate_profiler
+        self.timeout = timeout
+        self._previous_context = None
+
+    def __enter__(self):
+        self._previous_context = {
+            "device": getattr(self._local, "device", None),
+            "device_map": getattr(self._local, "device_map", None),
+            "create_runtimes": getattr(self._local, "create_runtimes", None),
+            "activate_profiler": getattr(self._local, "activate_profiler", None),
+            "timeout": getattr(self._local, "timeout", None),
+        }
+
+        if self.device is not None:
+            self._local.device = self.device
+        if self.device_map is not None:
+            self._local.device_map = self.device_map
+        if self.create_runtimes is not None:
+            self._local.create_runtimes = self.create_runtimes
+        if self.activate_profiler is not None:
+            self._local.activate_profiler = self.activate_profiler
+        if self.timeout is not None:
+            self._local.timeout = self.timeout
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._previous_context is not None:
+            self._local.device = self._previous_context["device"]
+            self._local.device_map = self._previous_context["device_map"]
+            self._local.create_runtimes = self._previous_context["create_runtimes"]
+            self._local.activate_profiler = self._previous_context["activate_profiler"]
+            self._local.timeout = self._previous_context["timeout"]
+
+    @classmethod
+    def get_current_context(cls):
+        return {
+            "device": getattr(cls._local, "device", None),
+            "device_map": getattr(cls._local, "device_map", None),
+            "create_runtimes": getattr(cls._local, "create_runtimes", None),
+            "activate_profiler": getattr(cls._local, "activate_profiler", None),
+            "timeout": getattr(cls._local, "timeout", None),
+        }

optimum/rbln/utils/save_utils.py

@@ -0,0 +1,102 @@
+# Copyright 2022 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Copyright 2025 Rebellions Inc. All rights reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Refer to huggingface/optimum/blob/4fdeea77d71e79451ba53e0c1f9d8f37e9704268/optimum/utils/save_utils.py
+"""
+
+from pathlib import Path
+from typing import List, Union
+
+from transformers import AutoFeatureExtractor, AutoProcessor, AutoTokenizer
+
+from .logging import get_logger
+
+
+logger = get_logger(__name__)
+
+
+def maybe_load_preprocessors(
+    src_name_or_path: Union[str, Path], subfolder: str = "", trust_remote_code: bool = False
+) -> List:
+    preprocessors = []
+    try:
+        preprocessors.append(
+            AutoTokenizer.from_pretrained(src_name_or_path, subfolder=subfolder, trust_remote_code=trust_remote_code)
+        )
+    except Exception:
+        pass
+
+    try:
+        preprocessors.append(
+            AutoProcessor.from_pretrained(src_name_or_path, subfolder=subfolder, trust_remote_code=trust_remote_code)
+        )
+    except Exception:
+        pass
+
+    try:
+        preprocessors.append(
+            AutoFeatureExtractor.from_pretrained(
+                src_name_or_path, subfolder=subfolder, trust_remote_code=trust_remote_code
+            )
+        )
+    except Exception:
+        pass
+    return preprocessors
+
+
+def maybe_save_preprocessors(
+    src_name_or_path: Union[str, Path],
+    dest_dir: Union[str, Path],
+    src_subfolder: str = "",
+    trust_remote_code: bool = False,
+):
+    """
+    Saves the tokenizer, the processor and the feature extractor when found in `src_dir` in `dest_dir`.
+
+    Args:
+        src_dir (`Union[str, Path]`):
+            The source directory from which to copy the files.
+        dest_dir (`Union[str, Path]`):
+            The destination directory to copy the files to.
+        src_subfolder (`str`, defaults to `""`):
+            In case the preprocessor files are located inside a subfolder of the model directory / repo on the Hugging
+            Face Hub, you can specify the subfolder name here.
+        trust_remote_code (`bool`, defaults to `False`):
+            Whether to allow to save preprocessors that is allowed to run arbitrary code. Use this option at your own risk.
+    """
+    if not isinstance(dest_dir, Path):
+        dest_dir = Path(dest_dir)
+
+    dest_dir.mkdir(exist_ok=True)
+    preprocessors = maybe_load_preprocessors(
+        src_name_or_path, subfolder=src_subfolder, trust_remote_code=trust_remote_code
+    )
+    for preprocessor in preprocessors:
+        preprocessor.save_pretrained(dest_dir)
+    return preprocessors

optimum/rbln/utils/submodule.py

@@ -0,0 +1,152 @@
+# Copyright 2025 Rebellions Inc. All rights reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type, Union
+
+from transformers import PretrainedConfig
+
+from ..configuration_utils import RBLNModelConfig, get_rbln_config_class
+from ..utils.model_utils import get_rbln_model_cls
+
+
+if TYPE_CHECKING:
+    from transformers import AutoFeatureExtractor, AutoProcessor, AutoTokenizer, PreTrainedModel
+
+    from ..modeling import RBLNModel
+
+
+class SubModulesMixin:
+    """
+    _rbln_submodules = [
+        {"name": "vision_tower"},
+        {"name": "language_model"},
+    ]
+    """
+
+    _rbln_submodules: List[Dict[str, Any]] = []
+
+    def __init__(self, *, rbln_submodules: List["RBLNModel"] = [], **kwargs) -> None:
+        for submodule_meta, submodule in zip(self._rbln_submodules, rbln_submodules):
+            setattr(self, submodule_meta["name"], submodule)
+
+    @classmethod
+    def _get_submodule_config_class(
+        cls, cls_name: str, submodule_rbln_config: Dict[str, Any]
+    ) -> Type[RBLNModelConfig]:
+        if isinstance(submodule_rbln_config, dict) and "cls_name" in submodule_rbln_config:
+            config_cls_name = submodule_rbln_config["cls_name"]
+            return get_rbln_config_class(config_cls_name)
+        return get_rbln_config_class(f"RBLN{cls_name}Config")
+
+    @classmethod
+    def _update_submodule_config(
+        cls,
+        model: "PreTrainedModel",
+        rbln_config: RBLNModelConfig,
+        preprocessors: Optional[Union["AutoFeatureExtractor", "AutoProcessor", "AutoTokenizer"]],
+    ):
+        return rbln_config
+
+    @classmethod
+    def _export_submodules_from_model(
+        cls, model: "PreTrainedModel", model_save_dir: str, rbln_config: RBLNModelConfig, **kwargs
+    ) -> List["RBLNModel"]:
+        rbln_submodules = []
+        submodule_prefix = getattr(cls, "_rbln_submodule_prefix", None)
+        preprocessors = kwargs.pop("preprocessors", [])
+
+        for submodule in cls._rbln_submodules:
+            submodule_name = submodule["name"]
+            if submodule_prefix is not None:
+                torch_submodule: PreTrainedModel = getattr(model, submodule_prefix)
+                torch_submodule = getattr(torch_submodule, submodule_name)
+            else:
+                torch_submodule: PreTrainedModel = getattr(model, submodule_name)
+
+            cls_name = torch_submodule.__class__.__name__
+            submodule_cls: Type["RBLNModel"] = get_rbln_model_cls(f"RBLN{cls_name}")
+            submodule_rbln_config = getattr(rbln_config, submodule_name) or {}
+            submodule_config_cls = cls._get_submodule_config_class(cls_name, submodule_rbln_config)
+
+            if isinstance(submodule_rbln_config, dict):
+                filtered_kwargs = rbln_config.filter_parameters(submodule_config_cls, submodule_rbln_config)
+                filtered_kwargs["cls_name"] = submodule_config_cls.__name__
+                submodule_rbln_config = submodule_config_cls(**filtered_kwargs)
+            elif not isinstance(submodule_rbln_config, submodule_config_cls):
+                config_dict = {k: v for k, v in submodule_rbln_config.__dict__.items() if not k.startswith("_")}
+                filtered_kwargs = rbln_config.filter_parameters(submodule_config_cls, config_dict)
+                filtered_kwargs["cls_name"] = submodule_config_cls.__name__
+                submodule_rbln_config = submodule_config_cls(**filtered_kwargs)
+
+            setattr(rbln_config, submodule_name, submodule_rbln_config)
+            submodule_rbln_config = submodule_cls._update_submodule_config(model, submodule_rbln_config, preprocessors)
+
+            rbln_submodule = submodule_cls.from_model(
+                model=torch_submodule,
+                config=torch_submodule.config,
+                subfolder=submodule_name,
+                model_save_dir=model_save_dir,
+                rbln_config=submodule_rbln_config,
+                **kwargs,
+            )
+
+            rbln_submodules.append(rbln_submodule)
+
+        return rbln_submodules
+
+    @classmethod
+    def _load_submodules_from_compiled_models(cls, model_save_dir: str, rbln_config: RBLNModelConfig, **kwargs):
+        rbln_submodules = []
+
+        for submodule in cls._rbln_submodules:
+            submodule_name = submodule["name"]
+
+            # Get cls name for call the constructor of the rbln class
+            submodule_rbln_config = getattr(rbln_config, submodule_name)
+
+            # RBLNModelConfig -> RBLNModel
+            submodule_cls = get_rbln_model_cls(submodule_rbln_config.rbln_model_cls_name)
+
+            json_file_path = Path(model_save_dir) / submodule_name / "config.json"
+            config = PretrainedConfig.from_json_file(json_file_path)
+
+            rbln_submodule = submodule_cls._from_pretrained(
+                model_id=model_save_dir,
+                config=config,
+                subfolder=submodule_name,
+                rbln_config=submodule_rbln_config,
+                **kwargs,
+            )
+
+            # update submodule's rbln_config since it is updated in the from_pretrained method
+            setattr(rbln_config, submodule_name, rbln_submodule.rbln_config)
+            rbln_submodules.append(rbln_submodule)
+
+        return rbln_submodules
+
+    @classmethod
+    def _load_submodules(cls, model_save_dir, rbln_config: RBLNModelConfig, model=None, **kwargs):
+        # Two ways :
+        # 1. Compile from pytorch object
+        # 2. Load from compiled file
+        if model is not None:
+            return cls._export_submodules_from_model(
+                model=model, model_save_dir=model_save_dir, rbln_config=rbln_config, **kwargs
+            )
+
+        else:
+            return cls._load_submodules_from_compiled_models(
+                model_save_dir=model_save_dir, rbln_config=rbln_config, **kwargs
+            )

optimum_rbln-0.9.3.post1.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: optimum-rbln
+Version: 0.9.3.post1
+Summary: Optimum RBLN is the interface between the HuggingFace Transformers and Diffusers libraries and RBLN accelerators. It provides a set of tools enabling easy model loading and inference on single and multiple rbln device settings for different downstream tasks.
+Project-URL: Homepage, https://rebellions.ai
+Project-URL: Documentation, https://docs.rbln.ai
+Project-URL: Repository, https://github.com/rebellions-sw/optimum-rbln
+Author-email: "Rebellions Inc." <support@rebellions.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: atom,diffusers,inference,rbln,rebel,transformers
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.9
+Requires-Dist: accelerate>=1.0.1
+Requires-Dist: diffusers==0.35.2
+Requires-Dist: packaging>=24.1
+Requires-Dist: torch==2.8.0
+Requires-Dist: torchaudio<=2.8.0
+Requires-Dist: torchvision<=0.23.0
+Requires-Dist: transformers==4.57.1
+Description-Content-Type: text/markdown
+
+
+# Optimum RBLN
+
+<div align="center">
+
+<img src="assets/rbln_logo.png" width="60%"/>
+
+[![PyPI version](https://badge.fury.io/py/optimum-rbln.svg)](https://badge.fury.io/py/optimum-rbln)
+[![License](https://img.shields.io/github/license/rebellions-sw/optimum-rbln)](https://github.com/rebellions-sw/optimum-rbln/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://docs.rbln.ai/software/optimum/optimum_rbln.html)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
+
+
+</div>
+
+🤗 Optimum RBLN provides an interface between HuggingFace libraries ([Transformers](https://huggingface.co/docs/transformers), [Diffusers](https://huggingface.co/docs/diffusers/index)) and RBLN NPUs, including [ATOM](https://rebellions.ai/rebellions-product/rbln-ca25/) and [REBEL](https://rebellions.ai/rebellions-product/rebel/).
+
+This library enables seamless integration between the HuggingFace ecosystem and RBLN NPUs through a comprehensive toolkit for model loading and inference across single and multi-NPU environments. While we maintain a list of [officially validated models and tasks](https://docs.rbln.ai/software/optimum/optimum_rbln.html), users can easily adapt other models and tasks with minimal modifications.
+
+## Key Features
+
+🚀 **High Performance Inference**
+- Optimized model execution on RBLN NPUs through RBLN SDK compilation
+- Support for both single and multi-NPU inference
+- Integrated with RBLN Runtime for optimal performance
+
+🔧 **Easy Integration**
+- Seamless compatibility with HuggingFace Model Hub
+- Drop-in replacement for existing HuggingFace pipelines
+- Minimal code changes required for NPU acceleration
+
+
+## Seamless Replacement for Existing HuggingFace Code
+
+```diff
+- from diffusers import StableDiffusionXLPipeline
++ from optimum.rbln import RBLNStableDiffusionXLPipeline
+
+# Load model
+model_id = "stabilityai/stable-diffusion-xl-base-1.0"
+prompt = "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k"
+- pipe = StableDiffusionXLPipeline.from_pretrained(model_id)
++ pipe = RBLNStableDiffusionXLPipeline.from_pretrained(model_id, export=True)
+
+# Generate image
+image = pipe(prompt).images[0]
+
+# Save image result
+image.save("image.png")
+
++ # (Optional) Save compiled artifacts to skip the compilation step in future runs
++ pipe.save_pretrained("compiled_sdxl")
+```
+
+## Documentation
+
+Check out [the documentation of Optimum RBLN](https://docs.rbln.ai/software/optimum/optimum_rbln.html) for more advanced usage.
+
+## Getting Started
+
+> **Note:** The `rebel-compiler` library, which is required for running `optimum-rbln`, is only available for approved users. Please refer to the [installation guide](https://docs.rbln.ai/getting_started/installation_guide.html) for instructions on accessing and installing `rebel-compiler`.
+
+### Install from PyPI
+
+To install the latest release of this package:
+```bash
+pip install optimum-rbln
+
+# CPU-only installation (recommended if you don't plan to use CUDA-enabled PyTorch)
+pip install optimum-rbln --extra-index-url https://download.pytorch.org/whl/cpu
+```
+
+### Install from source
+
+#### Prerequisites
+
+- Install [uv](https://docs.astral.sh/uv/) (refer to [this link](https://docs.astral.sh/uv/getting-started/installation/) for detailed commands)
+
+The below command installs `optimum-rbln` along with its dependencies.
+
+```bash
+git clone https://github.com/rebellions-sw/optimum-rbln.git
+cd optimum-rbln
+./scripts/uv-sync.sh
+```
+
+### Need Help?
+
+- Join discussions and get answers in our [Developer Community](https://discuss.rebellions.ai/)
+- Contact maintainers at [support@rebellions.ai](mailto:support@rebellions.ai)