omnibase_spi 0.12.0

ONEX Service Provider Interface - Protocol definitions

ONEX Service Provider Interface (omnibase_spi)

Pure protocol interfaces for the ONEX framework with zero implementation dependencies.

Table of Contents

• Quick Start
• V0.3.0 Highlights
• Architecture
• Repository Structure
• Protocol Overview
• Key Features
• Exception Hierarchy
• Protocol Design Guidelines
• Development
• Namespace Isolation
• Contributing
• Documentation
• See Also
• License
• Support

Quick Start

# Install with uv
uv add omnibase-spi

# Or with pip
pip install omnibase-spi

# Import node protocols
from omnibase_spi.protocols.nodes import (
    ProtocolNode,
    ProtocolComputeNode,
    ProtocolEffectNode,
    ProtocolReducerNode,
    ProtocolOrchestratorNode,
)

# Import handler protocol
from omnibase_spi.protocols.handlers import ProtocolHandler

# Import registry protocol
from omnibase_spi.protocols.registry import ProtocolHandlerRegistry

# Import contract compilers
from omnibase_spi.protocols.contracts import (
    ProtocolEffectContractCompiler,
    ProtocolWorkflowContractCompiler,
    ProtocolFSMContractCompiler,
)

# Import exception hierarchy
from omnibase_spi.exceptions import (
    SPIError,
    ProtocolHandlerError,
    ContractCompilerError,
    RegistryError,
)

V0.3.0 Highlights

• Node Protocols: Complete node type hierarchy with ProtocolNode, ProtocolComputeNode, ProtocolEffectNode, ProtocolReducerNode, and ProtocolOrchestratorNode
• Handler Protocol: ProtocolHandler with full lifecycle management (initialize, execute, shutdown)
• Contract Compilers: Effect, Workflow, and FSM contract compilation protocols
• Handler Registry: ProtocolHandlerRegistry for dependency injection and handler lookup
• Exception Hierarchy: Structured SPIError base with specialized subclasses
• 180+ Protocols: Comprehensive coverage across 23 specialized domains

Architecture

+-----------------------------------------------------------+
|                      Applications                          |
|               (omniagent, omniintelligence)                |
+-----------------------------+-----------------------------+
                              | uses
                              v
+-----------------------------------------------------------+
|                      omnibase_spi                          |
|            (Protocol Contracts, Exceptions)                |
|  - ProtocolNode, ProtocolComputeNode, ProtocolEffectNode   |
|  - ProtocolHandler, ProtocolHandlerRegistry                |
|  - Contract Compilers (Effect, Workflow, FSM)              |
+-----------------------------+-----------------------------+
                              | imports models
                              v
+-----------------------------------------------------------+
|                      omnibase_core                         |
|             (Pydantic Models, Core Types)                  |
+-----------------------------+-----------------------------+
                              | implemented by
                              v
+-----------------------------------------------------------+
|                      omnibase_infra                        |
|          (Handler Implementations, I/O)                    |
+-----------------------------------------------------------+

Related Repositories:

• omnibase_spi - This repository (Protocol contracts)
• omnibase_core - Pydantic models and core types
• omnibase_infra - Concrete implementations

Dependency Rules:

• SPI -> Core: allowed (runtime imports of models and contract types)
• Core -> SPI: forbidden (no imports)
• SPI -> Infra: forbidden (no imports, even transitively)
• Infra -> SPI + Core: expected (implements behavior)

Repository Structure

src/omnibase_spi/
+-- protocols/
|   +-- nodes/               # Node type protocols
|   |   +-- base.py          #   ProtocolNode
|   |   +-- compute.py       #   ProtocolComputeNode
|   |   +-- effect.py        #   ProtocolEffectNode
|   |   +-- reducer.py       #   ProtocolReducerNode
|   |   +-- orchestrator.py  #   ProtocolOrchestratorNode
|   |   +-- legacy/          #   Deprecated protocols (removal in v0.5.0)
|   +-- handlers/            # Handler protocol
|   |   +-- protocol_handler.py
|   +-- contracts/           # Contract compiler protocols
|   |   +-- effect_compiler.py
|   |   +-- workflow_compiler.py
|   |   +-- fsm_compiler.py
|   +-- registry/            # Handler registry protocol
|   |   +-- handler_registry.py
|   +-- container/           # DI and service registry
|   +-- event_bus/           # Event bus protocols
|   +-- workflow_orchestration/  # Workflow protocols
|   +-- mcp/                 # MCP integration protocols
|   +-- [14 more domains]
+-- exceptions.py            # SPIError hierarchy
+-- py.typed                 # PEP 561 marker

Protocol Overview

The ONEX SPI provides 180+ protocols across 23 specialized domains:

Domain	Protocols	Description
Nodes	5	Node type hierarchy (Compute, Effect, Reducer, Orchestrator)
Handlers	1	Protocol handler with lifecycle management
Contracts	3	Contract compilers (Effect, Workflow, FSM)
Registry	1	Handler registry for DI
Container	21	Dependency injection, lifecycle management
Event Bus	13	Distributed messaging infrastructure
Workflow Orchestration	14	Event-driven FSM coordination
MCP Integration	15	Multi-subsystem tool coordination
Memory	15	Workflow state persistence
Core System	16	Logging, health monitoring, error handling
Plus 22 more domains	76+	Validation, networking, file handling, etc.

Key Features

• Zero Implementation Dependencies - Pure protocol contracts only
• Runtime Type Safety - Full @runtime_checkable protocol support
• Dependency Injection - Sophisticated service lifecycle management
• Event-Driven Architecture - Event sourcing and workflow orchestration
• Multi-Subsystem Coordination - MCP integration and distributed tooling
• Enterprise Features - Health monitoring, metrics, circuit breakers

Exception Hierarchy

SPIError                          # Base exception for all SPI errors
+-- ProtocolHandlerError          # Handler execution errors
|   +-- HandlerInitializationError  # Handler failed to initialize
+-- ContractCompilerError         # Contract compilation/validation errors
+-- RegistryError                 # Handler registry operation errors
+-- ProtocolNotImplementedError   # Missing protocol implementation
+-- InvalidProtocolStateError     # Lifecycle state violations

Protocol Design Guidelines

Protocol Definition Pattern

from typing import Protocol, runtime_checkable
from omnibase_core.models.compute import ModelComputeInput, ModelComputeOutput

@runtime_checkable
class ProtocolComputeNode(Protocol):
    """Compute node for pure transformations."""

    @property
    def is_deterministic(self) -> bool:
        """Whether this node produces deterministic output."""
        ...

    async def execute(self, input_data: ModelComputeInput) -> ModelComputeOutput:
        """Execute the compute operation."""
        ...

Protocol Requirements

Every protocol must:

1. Inherit from typing.Protocol
2. Have @runtime_checkable decorator
3. Use ... (ellipsis) for method bodies
4. Import Core models for type hints (allowed at runtime)
5. Have docstrings with Args/Returns/Raises

Development

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run single test file
uv run pytest tests/path/to/test_file.py

# Run single test
uv run pytest tests/path/to/test_file.py::test_name -v

# Type checking
uv run mypy src/

# Strict type checking (target for CI)
uv run mypy src/ --strict

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Build package
uv build

# Run standalone validators (stdlib only, no dependencies)
python scripts/validation/run_all_validations.py
python scripts/validation/run_all_validations.py --strict --verbose

# Individual validators
python scripts/validation/validate_naming_patterns.py src/
python scripts/validation/validate_namespace_isolation.py
python scripts/validation/validate_architecture.py --verbose

# Pre-commit hooks
pre-commit run --all-files
pre-commit run validate-naming-patterns --all-files
pre-commit run validate-namespace-isolation-new --all-files

Namespace Isolation

This SPI package maintains complete namespace isolation to prevent circular dependencies:

Rule	Status
from omnibase_spi.protocols.* import ...	Allowed
from omnibase_core.* import ...	Allowed
from omnibase_infra.* import ...	Forbidden
Pydantic models in SPI	Forbidden (use Core)

Contributing

We welcome contributions! Please see our Contributing Guide for development guidelines.

# Clone the repository
git clone https://github.com/OmniNode-ai/omnibase_spi.git
cd omnibase_spi

# Install dependencies
uv sync --group dev

# Run validation
uv run pre-commit run --all-files

Documentation

• Complete Documentation - Comprehensive protocol documentation
• API Reference - All 180+ protocols across 23 domains
• Quick Start Guide - Get up and running in minutes
• Developer Guide - Development workflow and best practices
• Architecture Overview - Design principles and patterns
• Protocol Sequence Diagrams - Interaction patterns
• Glossary - Terminology and definitions
• Changelog - Version history and release notes

See the Glossary for definitions of SPI-specific terms like Protocol, Handler, Node, and Contract.

See Also

• Contributing Guide - How to contribute to the project
• MVP Plan - v0.3.0 work breakdown and architecture
• CLAUDE.md - AI assistant guidance for working with this repository

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Complete Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Made with care by the OmniNode Team