Metadata-Version: 2.4
Name: omnibase_core
Version: 0.23.0
Summary: ONEX Core Framework - Base classes and essential implementations
Project-URL: homepage, https://github.com/OmniNode-ai/omnibase_core
Project-URL: repository, https://github.com/OmniNode-ai/omnibase_core
Project-URL: documentation, https://github.com/OmniNode-ai/omnibase_core/tree/main/docs
Author-email: OmniNode Team <team@omninode.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,base-classes,dependency-injection,error-handling,event-driven,framework,infrastructure,node-architecture,onex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: blake3<2.0.0,>=1.0.8
Requires-Dist: click<9.0.0,>=8.3.1
Requires-Dist: cryptography<47.0.0,>=46.0.3
Requires-Dist: deepdiff<9.0.0,>=8.0.0
Requires-Dist: dependency-injector<5.0.0,>=4.48.3
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: jsonschema<5.0.0,>=4.25.1
Requires-Dist: omnibase-spi==0.15.0
Requires-Dist: pydantic<3.0.0,>=2.12.5
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Provides-Extra: cache
Requires-Dist: redis<8.0.0,>=5.0.0; extra == 'cache'
Provides-Extra: cli
Requires-Dist: psutil>=7.2.1; extra == 'cli'
Provides-Extra: full
Requires-Dist: prometheus-client<1.0.0,>=0.21.0; extra == 'full'
Requires-Dist: psutil>=7.2.1; extra == 'full'
Requires-Dist: redis<8.0.0,>=5.0.0; extra == 'full'
Requires-Dist: sqlglot<30.0.0,>=26.0.0; extra == 'full'
Provides-Extra: metrics
Requires-Dist: prometheus-client<1.0.0,>=0.21.0; extra == 'metrics'
Provides-Extra: sql-parser
Requires-Dist: sqlglot<30.0.0,>=26.0.0; extra == 'sql-parser'
Description-Content-Type: text/markdown

# ONEX Core Framework

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Linting: ruff](https://img.shields.io/badge/linting-ruff-261230.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy.readthedocs.io/)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Framework: Core](https://img.shields.io/badge/framework-core-purple.svg)](https://github.com/OmniNode-ai/omnibase_core)
[![Node Types: 4](https://img.shields.io/badge/node%20types-4-blue.svg)](https://github.com/OmniNode-ai/omnibase_core)

**Contract-driven execution layer for tools and workflows.** Deterministic execution, zero boilerplate, full observability.

## What is ONEX?

**ONEX is a declarative, contract-driven execution layer for tools and distributed workflows.** It standardizes how agents execute, communicate, and share context. Instead of custom glue code for each agent or tool, ONEX provides a deterministic execution protocol that behaves the same from local development to distributed production.

Use ONEX when you need predictable, testable, observable agent tools with consistent error handling across distributed systems.

## Four-Node Architecture

```text
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   EFFECT    │───▶│   COMPUTE   │───▶│   REDUCER   │───▶│ORCHESTRATOR │
│   (I/O)     │    │ (Transform) │    │(Aggregate)  │    │(Coordinate) │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
```

- **EFFECT**: External interactions (APIs, DBs, queues)
- **COMPUTE**: Transformations and pure logic
- **REDUCER**: State aggregation, finite state machines
- **ORCHESTRATOR**: Multi-step workflows, coordination

Unidirectional flow only. No backwards dependencies.

**See**: [ONEX Four-Node Architecture](docs/architecture/ONEX_FOUR_NODE_ARCHITECTURE.md)

## Why ONEX Exists

Most agent frameworks reinvent execution logic, leading to:
- inconsistent inputs/outputs
- implicit state
- opaque or framework-specific failures
- framework/vendor lock-in
- untestable tools

ONEX solves this with:
- typed schemas (Pydantic + protocols)
- deterministic lifecycle
- event-driven contracts: `ModelEventEnvelope`
- full traceability
- framework-agnostic design

## What This Repository Provides

OmniBase Core is the execution engine used by all ONEX-compatible nodes and services.
- Base classes that remove 80+ lines of boilerplate per node
- Protocol-driven dependency injection: `ModelONEXContainer`
- Structured errors with proper error codes: `ModelOnexError`
- Event system via `ModelEventEnvelope`
- Full 4-node architecture
- Mixins for reusable behaviors
- Subcontracts for declarative configuration

## Quick Start

Install:
```bash
uv add omnibase_core
```

Minimal example:
```python
from omnibase_core.nodes import NodeCompute, ModelComputeInput, ModelComputeOutput
from omnibase_core.models.container.model_onex_container import ModelONEXContainer

class NodeCalculator(NodeCompute):
    def __init__(self, container: ModelONEXContainer) -> None:
        super().__init__(container)

    async def process(self, input_data: ModelComputeInput) -> ModelComputeOutput:
        value = input_data.data.get("value", 0)
        return ModelComputeOutput(
            result={"result": value * 2},
            operation_id=input_data.operation_id,
            computation_type=input_data.computation_type,
        )
```

Run tests:
```bash
uv run pytest
```

**Next**: [Node Building Guide](docs/guides/node-building/README.md)

## How ONEX Compares

- **LangChain/LangGraph**: Pipeline-first. ONEX standardizes execution semantics.
- **Ray**: Distributed compute. ONEX focuses on agent tool determinism.
- **Temporal**: Workflow durability. ONEX defines tool and agent interaction.
- **Microservices**: Boundary-driven. ONEX defines the protocol services speak.

## Repository Structure

```text
src/omnibase_core/
├── backends/           # Cache (Redis) and metrics backends
├── container/          # DI container
├── crypto/             # Blake3 hashing, Ed25519 signing
├── enums/              # Core enumerations (300+ enums)
├── errors/             # Structured errors
├── infrastructure/     # NodeCoreBase, ModelService*
├── merge/              # Contract merge engine
├── mixins/             # Reusable behavior mixins (40+)
├── models/             # Pydantic models (80+ subdirectories)
├── nodes/              # EFFECT, COMPUTE, REDUCER, ORCHESTRATOR
├── protocols/          # Protocol interfaces
├── rendering/          # Report renderers (CLI, HTML, JSON, Markdown)
├── resolution/         # Dependency resolvers
├── schemas/            # JSON Schema definitions
├── services/           # Service implementations
├── validation/         # Validation framework + cross-repo validators
└── tools/              # Mypy plugins
```

**See**: [Architecture Overview](docs/architecture/overview.md)

## Advanced Topics

- **Subcontracts**: Declarative behavior modules. See [SUBCONTRACT_ARCHITECTURE.md](docs/architecture/SUBCONTRACT_ARCHITECTURE.md).
- **Manifest Models**: Typed metadata loaders. See [MANIFEST_MODELS.md](docs/reference/MANIFEST_MODELS.md).

## Thread Safety

Most ONEX nodes are not thread-safe. See [THREADING.md](docs/guides/THREADING.md).

## Documentation

**Start here**: [Node Building Guide](docs/guides/node-building/README.md)

**Reference**: [Complete Documentation Index](docs/INDEX.md)

## Development

Uses [uv](https://docs.astral.sh/uv/) for package management.

```bash
uv sync --all-extras
uv run pytest tests/
uv run mypy src/omnibase_core/
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

**See**: [CONTRIBUTING.md](CONTRIBUTING.md) for PR requirements.
