zep-protocol 0.1.0__tar.gz

zep_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: zep-protocol
+Version: 0.1.0
+Summary: ZEP — Zero Echo Pipe: lightweight inter-program communication protocol
+Author: zeroechosoft
+License: MIT
+Project-URL: Homepage, https://saintiron82.github.io/ZeroEchoPipe/
+Project-URL: Repository, https://github.com/saintiron82/ZeroEchoPipe
+Project-URL: Documentation, https://saintiron82.github.io/ZeroEchoPipe/
+Keywords: ipc,protocol,messaging,agent,rpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10

zep_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zep-protocol"
+version = "0.1.0"
+description = "ZEP — Zero Echo Pipe: lightweight inter-program communication protocol"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+keywords = ["ipc", "protocol", "messaging", "agent", "rpc"]
+authors = [
+    {name = "zeroechosoft"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage = "https://saintiron82.github.io/ZeroEchoPipe/"
+Repository = "https://github.com/saintiron82/ZeroEchoPipe"
+Documentation = "https://saintiron82.github.io/ZeroEchoPipe/"
+
+[tool.setuptools.packages.find]
+include = ["zep*"]

zep_protocol-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zep_protocol-0.1.0/tests/test_agent.py

@@ -0,0 +1,128 @@
+"""Tests for BaseAgent framework — decorator binding, agent-to-agent communication."""
+
+import os
+import sys
+import tempfile
+import time
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from zep.agent import BaseAgent, method, on_event
+from zep.peer import RemoteError
+from zep.transport.file import FileTransport
+
+
+class EchoAgent(BaseAgent):
+    """Simple agent that echoes params and tracks events."""
+
+    def __init__(self, *args, **kwargs):
+        self.received_events = []
+        super().__init__(*args, **kwargs)
+
+    @method("echo")
+    def handle_echo(self, params):
+        return params
+
+    @method("add")
+    def handle_add(self, params):
+        return {"sum": params["a"] + params["b"]}
+
+    @on_event("notify")
+    def handle_notify(self, params):
+        self.received_events.append(params)
+
+
+class TestAgentBasic(unittest.TestCase):
+    """Test BaseAgent decorator binding and method routing."""
+
+    def _setup_agents(self):
+        tmp_dir = tempfile.TemporaryDirectory()
+        transport_a = FileTransport(tmp_dir.name)
+        transport_b = FileTransport(tmp_dir.name)
+
+        server = EchoAgent("server", transport_a, session="test")
+        client = BaseAgent("client", transport_b, session="test")
+
+        server.run(blocking=False)
+
+        def cleanup():
+            server.stop()
+            transport_a.close()
+            transport_b.close()
+            tmp_dir.cleanup()
+
+        self.addCleanup(cleanup)
+        return server, client
+
+    def test_echo(self):
+        server, client = self._setup_agents()
+        result = client.call("server", "echo", {"msg": "hello"}, timeout_ms=5000)
+        self.assertEqual(result, {"msg": "hello"})
+
+    def test_add(self):
+        server, client = self._setup_agents()
+        result = client.call("server", "add", {"a": 3, "b": 4}, timeout_ms=5000)
+        self.assertEqual(result, {"sum": 7})
+
+    def test_event(self):
+        server, client = self._setup_agents()
+        client.emit("server", "notify", {"level": "info", "msg": "test"})
+        time.sleep(0.1)
+        self.assertEqual(len(server.received_events), 1)
+        self.assertEqual(server.received_events[0]["msg"], "test")
+
+    def test_capabilities(self):
+        server, client = self._setup_agents()
+        caps = client.call("server", "_capabilities", {}, timeout_ms=5000)
+        self.assertEqual(caps["name"], "server")
+        self.assertEqual(caps["agent_type"], "EchoAgent")
+        self.assertIn("echo", caps["methods"])
+        self.assertIn("add", caps["methods"])
+
+    def test_unknown_method(self):
+        server, client = self._setup_agents()
+        with self.assertRaises(RemoteError) as ctx:
+            client.call("server", "nonexistent", {}, timeout_ms=5000)
+        self.assertEqual(ctx.exception.code, "METHOD_NOT_FOUND")
+
+
+class TestAgentToAgent(unittest.TestCase):
+    """Two agents communicating with each other."""
+
+    def test_bidirectional(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            transport_a = FileTransport(tmp_dir)
+            transport_b = FileTransport(tmp_dir)
+
+            class AgentA(BaseAgent):
+                @method("greet")
+                def handle_greet(self, params):
+                    return {"reply": f"Hello, {params['name']}!"}
+
+            class AgentB(BaseAgent):
+                @method("status")
+                def handle_status(self, params):
+                    return {"online": True}
+
+            a = AgentA("alice", transport_a, session="s1")
+            b = AgentB("bob", transport_b, session="s1")
+
+            a.run(blocking=False)
+            b.run(blocking=False)
+
+            try:
+                # B calls A
+                result = b.call("alice", "greet", {"name": "Bob"}, timeout_ms=5000)
+                self.assertEqual(result, {"reply": "Hello, Bob!"})
+
+                # A calls B
+                result = a.call("bob", "status", {}, timeout_ms=5000)
+                self.assertEqual(result, {"online": True})
+            finally:
+                a.stop()
+                b.stop()
+
+
+if __name__ == "__main__":
+    unittest.main()

zep_protocol-0.1.0/tests/test_conformance.py

@@ -0,0 +1,98 @@
+"""ZEP protocol conformance test suite.
+
+Loads test cases from the shared conformance manifest and validates
+parse, parse-invalid, and serialize behaviour against expected outputs.
+"""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from zep.message import ValidationError, parse, serialize
+
+CONFORMANCE_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "conformance")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_json(path: str):
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _load_raw(path: str) -> str:
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+# ---------------------------------------------------------------------------
+# Manifest (loaded once at module level)
+# ---------------------------------------------------------------------------
+
+_MANIFEST = _load_json(os.path.join(CONFORMANCE_DIR, "manifest.json"))
+
+
+# ---------------------------------------------------------------------------
+# Test cases
+# ---------------------------------------------------------------------------
+
+class TestParseValid(unittest.TestCase):
+    """Input messages that must parse successfully."""
+
+    def test_parse_valid_cases(self):
+        for case in _MANIFEST["suites"]["parse_valid"]:
+            case_name = case.rsplit("/", 1)[-1]
+            with self.subTest(case=case_name):
+                raw = _load_raw(
+                    os.path.join(CONFORMANCE_DIR, f"{case}.input.json")
+                ).rstrip("\n")
+                expected_parsed = _load_json(
+                    os.path.join(CONFORMANCE_DIR, f"{case}.expected.json")
+                )["parsed"]
+                result = parse(raw)
+                self.assertEqual(result, expected_parsed)
+
+
+class TestParseInvalid(unittest.TestCase):
+    """Input messages that must be rejected with the correct error."""
+
+    def test_parse_invalid_cases(self):
+        for case in _MANIFEST["suites"]["parse_invalid"]:
+            case_name = case.rsplit("/", 1)[-1]
+            with self.subTest(case=case_name):
+                raw = _load_raw(
+                    os.path.join(CONFORMANCE_DIR, f"{case}.input.json")
+                ).rstrip("\n")
+                expected = _load_json(
+                    os.path.join(CONFORMANCE_DIR, f"{case}.expected.json")
+                )
+                with self.assertRaises(ValidationError) as ctx:
+                    parse(raw)
+                self.assertEqual(ctx.exception.code, expected["error_code"])
+                self.assertEqual(ctx.exception.field, expected["error_field"])
+
+
+class TestSerialize(unittest.TestCase):
+    """Field dicts that must serialize to byte-exact JSONL strings."""
+
+    def test_serialize_cases(self):
+        for case in _MANIFEST["suites"]["serialize"]:
+            case_name = case.rsplit("/", 1)[-1]
+            with self.subTest(case=case_name):
+                fields = _load_json(
+                    os.path.join(CONFORMANCE_DIR, f"{case}.fields.json")
+                )
+                expected_raw = _load_raw(
+                    os.path.join(CONFORMANCE_DIR, f"{case}.expected.jsonl")
+                )
+                result = serialize(fields, profile="jsonl")
+                self.assertEqual(result, expected_raw)
+
+
+if __name__ == "__main__":
+    unittest.main()

zep_protocol-0.1.0/tests/test_peer_advanced.py

@@ -0,0 +1,155 @@
+"""Tests for Peer advanced features — reserved methods, routing, shutdown."""
+
+import os
+import sys
+import tempfile
+import threading
+import time
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from zep.peer import Peer, CallTimeout, RemoteError
+from zep.transport.file import FileTransport
+
+
+class TestReservedMethods(unittest.TestCase):
+    """Test _capabilities, _ping, _shutdown protocol methods."""
+
+    def _make_peers(self):
+        tmp_dir = tempfile.TemporaryDirectory()
+        transport_a = FileTransport(tmp_dir.name)
+        transport_b = FileTransport(tmp_dir.name)
+
+        engine = Peer(transport_a, "engine", session="test_session",
+                      capabilities={"version": "0.1.0"})
+        agent = Peer(transport_b, "agent", session="test_session")
+
+        engine.bind("echo", lambda p: p)
+
+        stop = threading.Event()
+
+        def engine_loop():
+            while not stop.is_set():
+                engine.poll_once()
+                stop.wait(0.001)
+
+        t = threading.Thread(target=engine_loop, daemon=True)
+        t.start()
+
+        def cleanup():
+            stop.set()
+            t.join(timeout=1)
+            transport_a.close()
+            transport_b.close()
+            tmp_dir.cleanup()
+
+        self.addCleanup(cleanup)
+        return engine, agent
+
+    def test_capabilities(self):
+        engine, agent = self._make_peers()
+        result = agent.call("engine", "_capabilities", {}, timeout_ms=5000)
+        self.assertEqual(result["name"], "engine")
+        self.assertEqual(result["schema"], "zep.v0.1")
+        self.assertIn("echo", result["methods"])
+        self.assertEqual(result["version"], "0.1.0")
+
+    def test_ping(self):
+        engine, agent = self._make_peers()
+        result = agent.call("engine", "_ping", {}, timeout_ms=5000)
+        self.assertTrue(result["pong"])
+        self.assertIn("timestamp", result)
+
+    def test_shutdown(self):
+        engine, agent = self._make_peers()
+        shutdown_called = []
+        engine.on_shutdown(lambda: shutdown_called.append(True))
+
+        result = agent.call("engine", "_shutdown", {}, timeout_ms=5000)
+        self.assertTrue(result["acknowledged"])
+        self.assertTrue(engine.is_shutdown)
+        self.assertEqual(len(shutdown_called), 1)
+
+    def test_reserved_method_binding_blocked(self):
+        engine, agent = self._make_peers()
+        with self.assertRaises(ValueError):
+            engine.bind("_secret", lambda p: p)
+
+
+class TestRoutingSymmetry(unittest.TestCase):
+    """Test §3.3 routing symmetry verification."""
+
+    def test_session_mismatch_ignored(self):
+        """Response with wrong session should be ignored → timeout."""
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            transport = FileTransport(tmp_dir)
+
+            from zep.message import serialize
+            # Agent sends call
+            agent = Peer(transport, "agent", session="s1")
+
+            # Manually craft a response with wrong session
+            bad_response = {
+                "id": "resp1",
+                "session": "wrong_session",
+                "from": "engine",
+                "to": "agent",
+                "type": "response",
+                "timestamp": "2026-03-13T12:00:00.000Z",
+                "meta": {"schema": "zep.v0.1"},
+                "reply_to": "nonexistent",
+                "result": {"ok": True},
+            }
+            transport.send("agent", "engine", serialize(bad_response))
+
+            # Agent polls — should ignore the mismatched response
+            agent.poll_once()
+            # No crash = success. The response is silently ignored.
+
+
+class TestBindEvent(unittest.TestCase):
+    """Test separate event handler registration."""
+
+    def test_bind_event_separate(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            transport_a = FileTransport(tmp_dir)
+            transport_b = FileTransport(tmp_dir)
+
+            engine = Peer(transport_a, "engine", session="s1")
+            agent = Peer(transport_b, "agent", session="s1")
+
+            call_results = []
+            event_results = []
+
+            engine.bind("action", lambda p: call_results.append(p) or {"ok": True})
+            engine.bind_event("action", lambda p: event_results.append(p))
+
+            stop = threading.Event()
+
+            def engine_loop():
+                while not stop.is_set():
+                    engine.poll_once()
+                    stop.wait(0.001)
+
+            t = threading.Thread(target=engine_loop, daemon=True)
+            t.start()
+
+            try:
+                # Event uses event handler
+                agent.emit("engine", "action", {"type": "event"})
+                time.sleep(0.1)
+
+                # Call uses call handler
+                result = agent.call("engine", "action", {"type": "call"}, timeout_ms=5000)
+
+                self.assertEqual(len(event_results), 1)
+                self.assertEqual(event_results[0]["type"], "event")
+                self.assertEqual(result, {"ok": True})
+            finally:
+                stop.set()
+                t.join(timeout=1)
+
+
+if __name__ == "__main__":
+    unittest.main()

zep_protocol-0.1.0/tests/test_roundtrip.py

@@ -0,0 +1,106 @@
+"""ZEP Roundtrip Test — two peers communicate via file transport."""
+
+import os
+import sys
+import tempfile
+import threading
+import time
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from zep.peer import Peer, CallTimeout, RemoteError
+from zep.transport.file import FileTransport
+
+
+class TestRoundtrip(unittest.TestCase):
+
+    def _make_peers(self):
+        """Create a pair of peers connected via file transport."""
+        tmp_dir = tempfile.TemporaryDirectory()
+        self._tmp_dir = tmp_dir
+
+        transport_a = FileTransport(tmp_dir.name)
+        transport_b = FileTransport(tmp_dir.name)
+
+        engine = Peer(transport_a, "engine", session="test_session")
+        agent = Peer(transport_b, "agent", session="test_session")
+
+        stop = threading.Event()
+
+        def engine_loop():
+            while not stop.is_set():
+                engine.poll_once()
+                stop.wait(0.001)
+
+        t = threading.Thread(target=engine_loop, daemon=True)
+        t.start()
+
+        def cleanup():
+            stop.set()
+            t.join(timeout=1)
+            transport_a.close()
+            transport_b.close()
+            tmp_dir.cleanup()
+
+        self.addCleanup(cleanup)
+
+        return engine, agent
+
+    def test_basic_call(self):
+        """Program peer registers method, agent peer calls it."""
+        engine, agent = self._make_peers()
+        engine.bind("get_status", lambda p: {"health": 100, "fps": 60})
+
+        result = agent.call("engine", "get_status", {}, timeout_ms=5000)
+        self.assertEqual(result, {"health": 100, "fps": 60})
+
+    def test_echo(self):
+        """Echo handler returns params as-is."""
+        engine, agent = self._make_peers()
+        engine.bind("echo", lambda p: p)
+
+        result = agent.call("engine", "echo", {"msg": "hello"}, timeout_ms=5000)
+        self.assertEqual(result, {"msg": "hello"})
+
+    def test_unknown_method(self):
+        """Calling an unregistered method raises METHOD_NOT_FOUND."""
+        engine, agent = self._make_peers()
+
+        with self.assertRaises(RemoteError) as ctx:
+            agent.call("engine", "nonexistent", {}, timeout_ms=5000)
+        self.assertEqual(ctx.exception.code, "METHOD_NOT_FOUND")
+
+    def test_event(self):
+        """Fire-and-forget event is received by the engine."""
+        engine, agent = self._make_peers()
+        received = []
+        engine.bind("on_ping", lambda p: received.append(p))
+
+        agent.emit("engine", "on_ping", {"ts": "2026-03-13T12:00:00.000Z"})
+
+        time.sleep(0.1)
+        engine.poll_once()
+
+        self.assertEqual(len(received), 1)
+
+    def test_timeout(self):
+        """Extremely short timeout raises CallTimeout."""
+        engine, agent = self._make_peers()
+
+        with self.assertRaises(CallTimeout):
+            agent.call("engine", "get_status", {}, timeout_ms=1)
+
+    def test_internal_error(self):
+        """Handler that raises an exception produces INTERNAL_ERROR."""
+        engine, agent = self._make_peers()
+        engine.bind("crash", lambda p: 1 / 0)
+
+        with self.assertRaises(RemoteError) as ctx:
+            agent.call("engine", "crash", {}, timeout_ms=5000)
+        self.assertEqual(ctx.exception.code, "INTERNAL_ERROR")
+        self.assertTrue(ctx.exception.retryable)
+
+
+if __name__ == "__main__":
+    unittest.main()

zep_protocol-0.1.0/tests/test_scenario.py

@@ -0,0 +1,122 @@
+"""Scenario-based conformance test runner for ZEP.
+
+Interprets scenario JSON files that define step-by-step message exchanges
+between peers, verifying state transitions per spec section 3.
+"""
+
+import glob
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from zep.message import serialize, parse
+from zep.transport.file import FileTransport
+
+SCENARIO_DIR = os.path.join(
+    os.path.dirname(__file__), "..", "..", "conformance", "scenarios"
+)
+
+
+class TestScenario(unittest.TestCase):
+
+    def test_scenarios(self):
+        pattern = os.path.join(SCENARIO_DIR, "*.scenario.json")
+        scenario_files = sorted(glob.glob(pattern))
+        self.assertTrue(scenario_files, f"No scenario files found in {SCENARIO_DIR}")
+
+        for path in scenario_files:
+            name = os.path.basename(path)
+            with self.subTest(scenario=name):
+                with open(path, "r") as f:
+                    scenario = json.load(f)
+                self._run_scenario(scenario)
+
+    def _run_scenario(self, scenario):
+        pending_calls = {}   # msg_id -> "pending" | "completed" | "failed" | "timeout"
+        call_sessions = {}   # msg_id -> session (for symmetry check)
+
+        with tempfile.TemporaryDirectory() as base_dir:
+            transport = FileTransport(base_dir)
+
+            for step in scenario["steps"]:
+                if "action" in step:
+                    self._exec_action(step, transport, pending_calls, call_sessions)
+                elif "assert_state" in step:
+                    self._exec_assert(step, pending_calls)
+
+            transport.close()
+
+    def _exec_action(self, step, transport, pending_calls, call_sessions):
+        action = step["action"]
+
+        if action == "send":
+            message = step["message"]
+            serialized = serialize(message, profile="jsonl")
+            transport.send(
+                to_peer=message["to"],
+                from_peer=message["from"],
+                data=serialized,
+            )
+            if message["type"] == "call":
+                pending_calls[message["id"]] = "pending"
+                call_sessions[message["id"]] = message["session"]
+
+        elif action == "receive":
+            raw_messages = transport.recv(step["actor"])
+            expected_id = step["expect_message_id"]
+            parsed_msg = None
+
+            for raw in raw_messages:
+                candidate = parse(raw)
+                if candidate["id"] == expected_id:
+                    parsed_msg = candidate
+                    break
+
+            self.assertIsNotNone(
+                parsed_msg,
+                f"Expected message {expected_id} not found "
+                f"for actor {step['actor']}",
+            )
+
+            if (
+                parsed_msg["type"] in ("response", "error")
+                and "reply_to" in parsed_msg
+            ):
+                reply_to = parsed_msg["reply_to"]
+                if reply_to in pending_calls:
+                    original_session = call_sessions.get(reply_to)
+                    if original_session and parsed_msg["session"] != original_session:
+                        pass  # session mismatch: ignore per spec 3.4
+                    elif parsed_msg["type"] == "response":
+                        pending_calls[reply_to] = "completed"
+                    elif parsed_msg["type"] == "error":
+                        pending_calls[reply_to] = "failed"
+
+    def _exec_assert(self, step, pending_calls):
+        expected = step["assert_state"].get("pending_calls", {})
+        for msg_id, expected_status in expected.items():
+            if expected_status == "timeout":
+                actual = pending_calls.get(msg_id)
+                if actual == "pending":
+                    pending_calls[msg_id] = "timeout"
+                self.assertEqual(
+                    pending_calls.get(msg_id),
+                    "timeout",
+                    f"pending_calls[{msg_id}]: expected timeout, "
+                    f"got {pending_calls.get(msg_id)}",
+                )
+            else:
+                self.assertEqual(
+                    pending_calls.get(msg_id),
+                    expected_status,
+                    f"pending_calls[{msg_id}]: expected {expected_status}, "
+                    f"got {pending_calls.get(msg_id)}",
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()