---
id: omnibase-spi
version: "0.23.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# omnibase_spi — ONEX Service Provider Interface - Protocol definitions

License: permissive · Maintenance: active · Downloads: 137.7K/mo

## What it is and what it does

omnibase_spi is a Service Provider Interface package that defines the protocol contracts for ONEX (OmniNode eXecution), a distributed service execution framework. It contains 231 runtime-checkable Python Protocol definitions across 39 protocol domains, plus frozen data-only contracts for wire formats. The package deliberately contains only interface definitions and shared data shapes imported from omnibase_core—no implementations, business logic, transport clients, or I/O behavior. This separation of concerns allows implementation packages to implement the protocols while keeping the SPI layer stable and reusable.

The package enforces strict dependency direction: it imports from omnibase_core but never from implementation packages, and implementation packages import from it. This design lets application and product repositories depend on the SPI for type boundaries without coupling to any concrete implementation. It requires Python 3.12 or later and uses pydantic and typing_extensions as runtime dependencies.

Use it for:

- Define service boundaries in a microservices architecture where multiple teams implement the same protocol contracts independently.
- Establish type-safe interfaces for distributed services that need to be swapped or upgraded without breaking consumers.
- Create wire-format contracts for cross-service communication that remain stable even as underlying implementations evolve.
- Build plugin or adapter systems where third-party code must implement known protocol interfaces to integrate with a platform.
- Enforce architectural layering by making protocol definitions the only dependency between abstraction and implementation layers.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Defines runtime-checkable Protocol contracts and wire-format data contracts for the ONEX service execution framework, enabling type-safe service boundaries across distributed implementations.

Yes, if you are building a distributed service system or framework that needs stable, implementation-agnostic protocol definitions. The package is actively maintained, has no known vulnerabilities, and uses a permissive MIT license. It is still in Beta, so verify that the protocol surface is stable for your use case. Install it if you need to define service boundaries that multiple implementations can satisfy independently.

## Install

pip install omnibase-spi
uv add omnibase-spi
poetry add omnibase-spi

## Installing omnibase_spi

Before you install: Low install friction with a pure-Python wheel. Active maintenance with a recent release 42 days ago. Requires Python 3.12 or later and depends on omnibase_core, pydantic, and typing_extensions—all standard, lightweight dependencies.

License in practice: MIT license permits unrestricted use, modification, and distribution in both open-source and commercial projects with minimal obligations beyond attribution.

Quickstart:

pip install omnibase_spi

from typing import Protocol, runtime_checkable

@runtime_checkable
class ProtocolExampleService(Protocol):
    async def run(self, payload: bytes) -> bytes:
        ...

Requires Python 3.12 or later.

Verify before relying:

- Whether the 231 protocol files across 39 domains are all exported or only a subset is public API
- Performance characteristics when runtime_checkable protocols are used at scale in high-throughput services
- Stability guarantees for the protocol contract surface given the Beta development status

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 137.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

protocol definitions service interface, runtime checkable protocols python, service boundary contracts, spi service provider interface, distributed service type contracts, wire format data contracts, protocol driven architecture, service-interface, protocol-definitions, distributed-systems

[View on SkillFed](https://skillfed.io/packages/omnibase-spi) · [View on PyPI](https://pypi.org/project/omnibase-spi/)