OmniBase SPI

0.20.5 verified Fri May 01 auth: no python

ONEX Service Provider Interface – Protocol definitions for building service providers in the OmniNode ecosystem. Version 0.20.5 requires Python >=3.12. Active development with frequent releases (weekly/monthly).

pip install omnibase-spi

Common errors

error ImportError: cannot import name 'ContractSavingsEstimate' from 'omnibase_spi' ↓

cause Trying to import from the top-level package instead of the models submodule.

fix

Replace with: from omnibase_spi.models import ContractSavingsEstimate

error AttributeError: module 'omnibase_spi' has no attribute 'ProtocolExternalService' ↓

cause Protocol classes are in the protocols submodule.

fix

Use: from omnibase_spi.protocols import ProtocolExternalService

Warnings

breaking Python >=3.12 only: omnibase_spi uses new syntax features not available in older versions. ↓

fix Upgrade to Python 3.12+ or use an older version if unavoidable.

deprecated The env-prefix mandate from older SPI protocol contracts was removed in v0.18.0. Do not rely on environment variable prefix constraints. ↓

fix Remove any code that expects a mandatory prefix (e.g., 'ONEX_').

gotcha Protocol classes are defined in separate submodules (e.g., omnibase_spi.protocols, omnibase_spi.models). Importing from the top-level package may not work. ↓

fix Always use explicit submodule imports (e.g., from omnibase_spi.protocols import ...).

Imports

ContractSavingsEstimate

wrong

from omnibase_spi import ContractSavingsEstimate

correct

from omnibase_spi.models import ContractSavingsEstimate

Introduced in v0.19.0, lives in models submodule.

ProtocolExternalService

wrong

from omnibase_spi import ProtocolExternalService

correct

from omnibase_spi.protocols import ProtocolExternalService

Defined in protocols module since v0.20.5.

ModelDeliveryResult

from omnibase_spi.models import ModelDeliveryResult

Standard import path.

Quickstart

Basic usage: create a model instance and dump JSON.

from omnibase_spi.models import ContractSavingsEstimate

estimate = ContractSavingsEstimate(
    contract_id="123",
    estimated_savings=1000.0,
    currency="USD"
)
print(estimate.model_dump_json(indent=2))