Metadata-Version: 2.4
Name: nodus-protocol
Version: 0.1.0
Summary: Typed control-plane message contracts: RequestEnvelope, ResponseEnvelope, EventEnvelope
Author: Shawn Knight
License: MIT
Project-URL: Homepage, https://github.com/Masterplanner25/nodus-protocol
Project-URL: Repository, https://github.com/Masterplanner25/nodus-protocol
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# nodus-protocol

**Typed control-plane message contracts for Nodus AI systems.**

Defines the wire format for request/response/event envelopes exchanged
between Nodus components (gateway, agents, channels). JSON codec with a
`_type` discriminator for safe deserialization. No required external
dependencies — pure stdlib.

> **Status:** v0.1.0 — prepared, not yet published.

---

## Install

```bash
pip install nodus-protocol
```

---

## What it provides

| Component | Purpose |
|---|---|
| `RequestEnvelope` | Inbound request: `id`, `method`, `params` |
| `ResponseEnvelope` | Response: `id`, `ok`, `result` or `error` |
| `EventEnvelope` | Server-pushed event: `event_type`, `payload`, `timestamp` |
| `encode(envelope)` | Serialize to JSON string with `_type` discriminator |
| `decode(raw)` | Deserialize JSON string to typed envelope |
| `PROTOCOL_VERSION` | Current version string (`"1.0"`) |
| `is_compatible(v)` | Check interoperability with another version |

---

## Quick start

```python
from nodus_protocol import RequestEnvelope, ResponseEnvelope, encode, decode

req = RequestEnvelope(id="req-001", method="agent.run", params={"objective": "hello"})
wire = encode(req)
# '{"_type": "request", "id": "req-001", "method": "agent.run", ...}'

decoded = decode(wire)
assert isinstance(decoded, RequestEnvelope)
assert decoded.method == "agent.run"

resp = ResponseEnvelope(id="req-001", ok=True, result={"run_id": "run-abc"})
```

---

## Envelopes

**RequestEnvelope** — `id` (str), `method` (str), `params` (dict | None)

**ResponseEnvelope** — `id` (str), `ok` (bool), `result` (any | None), `error` (str | None)

**EventEnvelope** — `event_type` (str), `payload` (dict | None), `timestamp` (float, auto-set UTC epoch)

---

## Codec

```python
from nodus_protocol import encode, decode

wire = encode(envelope)    # JSON str with "_type" discriminator
envelope = decode(wire)    # RequestEnvelope | ResponseEnvelope | EventEnvelope
```

`decode` routes on `_type`. Raises `ValueError` on unknown type or malformed JSON.

---

## Versioning

```python
from nodus_protocol import PROTOCOL_VERSION, is_compatible

print(PROTOCOL_VERSION)   # "1.0"
is_compatible("1.0")      # True
is_compatible("1.1")      # True  (minor compatible)
is_compatible("2.0")      # False (major mismatch)
```

---

## Design

- **No required dependencies.** Pure stdlib (`json`, `dataclasses`, `datetime`).
- **`_type` discriminator.** Every encoded envelope includes `_type` so
  `decode` can reconstruct the correct class without out-of-band schema info.

---

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -q
```

---

## License

MIT — see [LICENSE](LICENSE).
