Metadata-Version: 2.4
Name: omnibase_core
Version: 0.9.7
Summary: ONEX Core Framework - Base classes and essential implementations
License-Expression: MIT
License-File: LICENSE
Keywords: onex,framework,architecture,dependency-injection,base-classes,infrastructure,event-driven,error-handling,node-architecture
Author: OmniNode Team
Author-email: team@omninode.ai
Requires-Python: >=3.12
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: cache
Provides-Extra: cli
Provides-Extra: full
Provides-Extra: metrics
Requires-Dist: click (>=8.1.0,<9.0.0)
Requires-Dist: cryptography (>=46.0.3,<47.0.0)
Requires-Dist: deepdiff (>=8.0.0,<9.0.0)
Requires-Dist: dependency-injector (>=4.48.1,<5.0.0)
Requires-Dist: httpx (>=0.27.0,<1.0.0)
Requires-Dist: jsonschema (>=4.25.1,<5.0.0)
Requires-Dist: prometheus-client (>=0.21.0,<1.0.0) ; extra == "full"
Requires-Dist: prometheus-client (>=0.21.0,<1.0.0) ; extra == "metrics"
Requires-Dist: psutil ; extra == "cli"
Requires-Dist: psutil ; extra == "full"
Requires-Dist: pydantic (>=2.11.7,<3.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: redis (>=5.0.0,<6.0.0) ; extra == "cache"
Requires-Dist: redis (>=5.0.0,<6.0.0) ; extra == "full"
Project-URL: Documentation, https://github.com/OmniNode-ai/omnibase_core/tree/main/docs
Project-URL: Homepage, https://github.com/OmniNode-ai/omnibase_core
Project-URL: Repository, https://github.com/OmniNode-ai/omnibase_core
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/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![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
poetry 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
poetry 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/
├── container/          # DI container
├── infrastructure/     # NodeCoreBase, ModelService*
├── models/             # Pydantic models
├── nodes/              # EFFECT, COMPUTE, REDUCER, ORCHESTRATOR
├── events/             # Event system
├── errors/             # Structured errors
└── mixins/             # Declarative behaviors
```

**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 Poetry for all package management.

```bash
poetry install
poetry run pytest tests/
poetry run mypy src/omnibase_core/
poetry run black src/ tests/
poetry run isort src/ tests/
```

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

