# RXON (Reverse Axon) Protocol

**EN** | [ES](https://github.com/madgagarin/rxon/blob/main/docs/es/README.md) | [RU](https://github.com/madgagarin/rxon/blob/main/docs/ru/README.md)

[![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/release/python-3110/)
[![PyPI version](https://img.shields.io/pypi/v/rxon.svg)](https://pypi.org/project/rxon/)

**RXON** (Reverse Axon) is a lightweight, extensible reverse-connection protocol designed for **[HLN (Hierarchical Logic Network)](https://github.com/avtomatika-ai/hln)** architectures.

It serves as the "nervous system" for distributed multi-agent systems, providing a strictly typed, Zero Trust foundation for inter-service communication.

## 🚀 Key Innovation: Version 1.0b6 (The Universal Update)

The latest version of RXON introduces a massive leap in flexibility and security, preparing the protocol for cross-platform industry standards.

-   **Zero Trust Security (SecurityContext)**: Built-in support for digital signatures and identity chains. Messages can now be cryptographically verified across infinite holarchy layers.
-   **Agnostic Design**: Core models (Resources, Skills, Tasks) are now fully extensible via universal `metadata` and `properties` fields.
-   **Smart Resource Matching**: Formalized logic for hardware requirements. Supports **GE (Greater or Equal)** logic for numbers and equality for strings, ensuring consistent dispatching across any implementation.
-   **Schema Dialects**: Holons can now negotiate data formats (JSON Schema, Protobuf, Pydantic-v2) via the `schema_dialect` field in skill contracts.

## ✨ Key Features

-   **Reverse Connection (PULL)**: The initiative always comes from the subordinate node (Shell), enabling operation behind NAT/Firewall without complex network setups.
-   **Generic Event System**: Unified signaling for progress updates, custom alerts, and real-time triggers with hierarchical event bubbling.
-   **Universal Telemetry**: Heartbeats include granular metrics for CPU, RAM, and any custom devices (Sensors, Robots, GPUs) via the extensible `HardwareDevice` model.
-   **Zero Dependency Core**: The protocol core is written in pure Python. Standard transports use `aiohttp` and `orjson` for peak performance.
-   **Blob Storage Native**: Direct support for offloading heavy data via S3-compatible storage (`rxon.blob`).

## 🏗 Architecture

The protocol is divided into two main interfaces:

1.  **Transport (Worker side)**: For initiating connections, retrieving tasks, emitting events, and sending results.
2.  **Listener (Orchestrator side)**: For accepting incoming connections and routing messages to the engine.

### Smart Dispatching Logic

RXON formalizes the rules for matching tasks to holons:
1.  **Identity Match**: Direct match by device ID.
2.  **Type & Model Match**: Exact match by type, partial match by model string.
3.  **Property Match (Smart Comparison)**:
    *   **Numbers**: Checked as **at least** (Worker value >= Requirement).
    *   **Others**: Checked as strict equality.

## 🛡️ Error Handling

RXON defines a set of standardized, cross-platform error codes:
-   `CONTRACT_VIOLATION_ERROR`: Data does not match the negotiated schema.
-   `SECURITY_ERROR`: Authentication or signature verification failed.
-   `RESOURCE_EXHAUSTED_ERROR`: Physical resources (RAM, VRAM) are insufficient.
-   `DEPENDENCY_ERROR`: A required service or artifact is unavailable.

## 🧪 Quick Start

```python
from rxon.models import Resources, HardwareDevice

# Define worker resources
my_res = Resources(
    cpu_cores=8,
    devices=[HardwareDevice(type="gpu", model="RTX 4090", properties={"memory_gb": 24})]
)

# Define task requirements
req = Resources(cpu_cores=4, devices=[HardwareDevice(type="gpu", properties={"memory_gb": 16})])

# Standardized Matching (HLN Protocol)
if my_res.matches(req):
    print("This holon is ready for the task!")
```

## 📜 License

The project is distributed under the Mozilla Public License 2.0 (MPL 2.0).

---
*Mantra: "The RXON is the medium for the Ghost."*
