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.4

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.4
File	Size	Uploaded
omnibase_spi-0.23.4.tar.gz	1.3 MB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for omnibase_spi 0.23.4
File	Interpreter	ABI	Platform	Reset
omnibase_spi-0.23.4-py3-none-any.whl 737.1 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 2.0 MB

Release files / omnibase_spi-0.23.4.tar.gz

Download URL	omnibase_spi-0.23.4.tar.gz
Size	1.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`364f8627cfd08a8b112339a1d934d54be332384686ae95ea368288992ecd7bbf`
BLAKE2b-256 checksum How to use checksums	`96124a6acb803f99f147c5206b61a7da412dda933cf2ef781f7460d1f1d1d1a2`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","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.4-py3-none-any.whl

Download URL	omnibase_spi-0.23.4-py3-none-any.whl
Size	737.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d46405f23e7d6b07ab816977f1798bd686d797f71c4a9dc6240f3d381095a682`
BLAKE2b-256 checksum How to use checksums	`49af5b307caa71ae161bfa6072e9b8d36d9cc607e0761d05c0620362300e4788`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.16 {"installer":{"name":"uv","version":"0.12.16","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}`