omninode

omnibase_spi

omnibase_spi is the Service Provider Interface package for ONEX (OmniNode eXecution). It defines protocol contracts, small wire-format contracts, and SPI exceptions that other repos implement or consume.

This package is intentionally not the implementation layer. Concrete runtime, transport, service, registry, and I/O behavior belongs in implementation repos such as omnibase_infra.

Current Role

Defines 232 protocol_*.py files across 39 protocol domains.
Provides runtime-checkable Python Protocol contracts for service boundaries.
Provides frozen, data-only contracts in src/omnibase_spi/contracts/ for selected cross-boundary wire formats.
Imports omnibase_core models and types where protocol signatures need shared platform data shapes.
Must not import implementation packages such as omnibase_infra.
Must not contain service implementations, business workflows, state machines, transport clients, or general domain Pydantic models.

Dependency Direction

The import direction is deliberate and non-obvious:

Application and product repos
        |
        v
omnibase_spi  ---- imports models/types ---->  omnibase_core
        ^                                      ^
        | implements protocols                 | uses models/types
        |
omnibase_infra and other implementation repos --+

Allowed:

omnibase_spi -> omnibase_core
omnibase_infra -> omnibase_spi
omnibase_infra -> omnibase_core
Product repos importing SPI protocols for type boundaries

Forbidden:

omnibase_core -> omnibase_spi
omnibase_spi -> omnibase_infra
Protocol files that perform I/O or instantiate concrete services
General domain BaseModel classes in SPI protocol modules

See Dependency Direction in the knowledge base for the full rule, examples, and rationale.

Install

uv add omnibase_spi

For local workspace development, use the repository lockfile and the configured omnibase-core source:

uv sync --group dev

Minimal Protocol Example

from typing import Protocol, runtime_checkable


@runtime_checkable
class ProtocolExampleService(Protocol):
    """Service boundary implemented outside omnibase_spi."""

    async def run(self, payload: bytes) -> bytes:
        """Run the service operation."""
        ...

Add A Protocol

Choose the domain under src/omnibase_spi/protocols/.
Create a protocol_<domain>_<name>.py file.
Name the public protocol Protocol<Name>.
Add @runtime_checkable.
Use ... method bodies only.
Import shared models from omnibase_core only when the signature requires canonical platform models or types.
Add or update tests under tests/.
Export the protocol from the domain __init__.py if it is public.

Common Commands

uv sync --group dev
uv run pytest
uv run mypy src/ --strict
uv run ruff check src/ tests/
uv run ruff format src/ tests/
python scripts/validation/run_all_validations.py
pre-commit run --all-files
uv build

Documentation

Full documentation → https://github.com/OmniNode-ai/knowledge-base

The knowledge base is the single home for this package's prose documentation: architecture, guides, patterns, standards, glossary, and testing. This repository keeps only what must ship beside the code.

Start here:

Kept in this repository:

API reference — versioned, generated against this package's code tag, so it cannot live in the knowledge base
Contributing, Security
Agent context — the single in-tree agent context file

License

MIT

Metadata

Release files for omnibase_spi 0.23.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for omnibase_spi 0.23.7
File	Size	Uploaded
omnibase_spi-0.23.7.tar.gz	1.3 MB	Oct 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for omnibase_spi 0.23.7
File	Interpreter	ABI	Platform	Reset
omnibase_spi-0.23.7-py3-none-any.whl 739.2 kB Oct 17, 2026	Python 3	none	any	Details

Total release size: 2.1 MB

Release files / omnibase_spi-0.23.7.tar.gz

Download URL	omnibase_spi-0.23.7.tar.gz
Size	1.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`2f0e5103a007c86e72916d9afc9bb7f9c7bdb41d809e6822300aee69b3ad866d`
BLAKE2b-256 checksum How to use checksums	`c5beb8603086668b7d79340f28efde87859ed594032a6f899e15118151628baa`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / omnibase_spi-0.23.7-py3-none-any.whl

Download URL	omnibase_spi-0.23.7-py3-none-any.whl
Size	739.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`797765ed280cecf85cc77f84bd4bc9d6ef6eb19a265158660b2b7df2a1167e10`
BLAKE2b-256 checksum How to use checksums	`d1732995dd0bcb79b3c6076b2619ea7f2338930c922ad3cee6b5232d6919237c`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`