nodus-protocol 0.1.0

Typed control-plane message contracts: RequestEnvelope, ResponseEnvelope, EventEnvelope

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

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

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

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

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

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

---

License

MIT — see LICENSE.