Metadata-Version: 2.4
Name: openvino_model_api
Version: 0.4.0
Summary: Model API: model wrappers and pipelines for inference with OpenVINO
Project-URL: Homepage, https://github.com/open-edge-platform/model_api
Project-URL: Documentation, https://github.com/open-edge-platform/model_api/blob/master/README.md
Project-URL: Repository, https://github.com/open-edge-platform/model_api.git
Author: Intel(R) Corporation
Maintainer: Intel(R) Corporation
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: numpy>=1.16.6
Requires-Dist: opencv-python-headless
Requires-Dist: openvino>=2025.3
Requires-Dist: pillow
Provides-Extra: docs
Requires-Dist: breathe; extra == 'docs'
Requires-Dist: graphviz; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: pandoc; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Provides-Extra: examples
Requires-Dist: httpx; extra == 'examples'
Requires-Dist: onnx; extra == 'examples'
Requires-Dist: onnxruntime; extra == 'examples'
Provides-Extra: huggingface
Requires-Dist: huggingface-hub; extra == 'huggingface'
Provides-Extra: onnx
Requires-Dist: onnx; extra == 'onnx'
Requires-Dist: onnxruntime; extra == 'onnx'
Provides-Extra: ovms
Requires-Dist: tritonclient[http]<2.59; extra == 'ovms'
Provides-Extra: tests
Requires-Dist: defusedxml; extra == 'tests'
Requires-Dist: httpx; extra == 'tests'
Requires-Dist: onnx; extra == 'tests'
Requires-Dist: onnxruntime; extra == 'tests'
Requires-Dist: pytest; extra == 'tests'
Requires-Dist: pytest-cov; extra == 'tests'
Requires-Dist: pytest-mock; extra == 'tests'
Requires-Dist: ultralytics<=8.0.205,>=8.0.114; extra == 'tests'
Provides-Extra: tools
Requires-Dist: huggingface-hub; extra == 'tools'
Requires-Dist: nncf; extra == 'tools'
Requires-Dist: timm; extra == 'tools'
Requires-Dist: torch; extra == 'tools'
Requires-Dist: torchvision; extra == 'tools'
Requires-Dist: transformers; extra == 'tools'
Requires-Dist: ultralytics; extra == 'tools'
Description-Content-Type: text/markdown

# OpenVINO Model API

[![PyPI](https://img.shields.io/pypi/v/openvino-model-api)](https://pypi.org/project/openvino-model-api)
[![Downloads](https://static.pepy.tech/personalized-badge/openvino-model-api?period=total&units=international_system&left_color=grey&right_color=green&left_text=PyPI%20Downloads)](https://pepy.tech/project/openvino-model-api)

[![Pre-Merge Test](https://github.com/open-edge-platform/model_api/actions/workflows/pre_commit.yml/badge.svg)](https://github.com/open-edge-platform/model_api/actions/workflows/pre_commit.yml)
[![Build Docs](https://github.com/open-edge-platform/model_api/actions/workflows/docs.yml/badge.svg)](https://github.com/open-edge-platform/model_api/actions/workflows/docs.yml)

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/open-edge-platform/model_api/badge)](https://scorecard.dev/viewer/?uri=github.com/open-edge-platform/model_api)

## Introduction

Model API is a set of wrapper classes for particular tasks and model architectures, simplifying data preprocess and postprocess as well as routine procedures (model loading, asynchronous execution, etc.). It is aimed at simplifying end-to-end model inference for different deployment scenarios, including local execution and serving. The Model API is based on the OpenVINO inference API.

## How it works

Model API searches for additional information required for model inference, data, pre/postprocessing, label names, etc. directly in OpenVINO Intermediate Representation. This information is used to prepare the inference data, process and output the inference results in a human-readable format.

Currently, ModelAPI supports models trained in [OpenVINO Training Extensions](https://github.com/openvinotoolkit/training_extensions) framework.
Training Extensions embed all the metadata required for inference into model file. For models coming from other than Training Extensions frameworks metadata generation step is required before using ModelAPI.

## Supported model formats

- [OpenVINO IR](https://docs.openvino.ai/2025/documentation/openvino-ir-format.html)
- [ONNX](https://onnx.ai)

## Features

- Python API
- Synchronous and asynchronous inference
- Local inference and serving through the REST API
- Model preprocessing embedding for faster inference

## Installation

`pip install openvino-model-api`

## Usage

```python
from model_api.models import Model

# Create a model wrapper from a compatible model generated by OpenVINO Training Extensions
# To work with an OVMS-served model, pass its endpoint instead of a file path, e.g. "localhost:8000/v2/models/ssdlite_mobilenet_v2"
model = Model.create_model("model.xml")

# Run synchronous inference locally
result = model(image)  # image is numpy.ndarray

# Print results in model-specific format
print(f"Inference result: {result}")
```

## Prepare a model for `InferenceAdapter`

There are usecases when it is not possible to modify an internal `ov::Model` and it is hidden behind `InferenceAdapter`. For example the model can be served using [OVMS](https://github.com/openvinotoolkit/model_server). `create_model()` can construct a model from a given `InferenceAdapter`. That approach assumes that the model in `InferenceAdapter` was already configured by `create_model()` called with a string (a path or a model name). It is possible to prepare such model:

```python
model = DetectionModel.create_model("~/.cache/omz/public/ssdlite_mobilenet_v2/FP16/ssdlite_mobilenet_v2.xml")
model.save("serialized.xml")
```

## Usage with generic OpenVINO models

ModelAPI uses custom field in `rt_info/model_info` section of OpenVINO IR to store metadata required for preprocessing and postprocessing. If you have a generic OpenVINO model without such metadata, you can provide that metadata in `configuration` argument of `create_model()` method:

```python
from model_api.models import Model

# Create a model wrapper from a compatible model generated by OpenVINO Training Extensions
model = Model.create_model(
    "model.xml",
    configuration={
        "model_type": "Segmentation",
        "blur_strength": 1,
        "labels": ["object"],
        "soft_threshold": 0.5,
    }
)

# Run synchronous inference locally
result = model(image)  # image is numpy.ndarray

# Print results in model-specific format
print(f"Inference result: {result}")

# Save the model with metadata already embedded (passing configuration is not required anymore)
model.save("serialized_with_metadata.xml")
```

For more details please refer to the [examples](https://github.com/openvinotoolkit/model_api/tree/master/examples) of this project.
