omnibase_spi 0.20.6

ONEX Service Provider Interface - Protocol definitions

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 248 protocol_*.py files across 37 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 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

1. Choose the domain under src/omnibase_spi/protocols/.
2. Create a protocol_<domain>_<name>.py file.
3. Name the public protocol Protocol<Name>.
4. Add @runtime_checkable.
5. Use ... method bodies only.
6. Import shared models from omnibase_core only when the signature requires canonical platform models or types.
7. Add or update tests under tests/.
8. 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

• Docs index
• Dependency direction
• Architecture overview
• API reference
• Developer guide
• Testing guide
• Contributing
• Security
• Agent context
• Claude context

License

MIT