keep-protocol 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

keep/__init__.py

@@ -2,5 +2,5 @@
 
 from keep.client import KeepClient
 
-__version__ = "0.1.1"
+__version__ = "0.3.0"
 __all__ = ["KeepClient"]

keep/client.py

@@ -1,19 +1,30 @@
 """Keep protocol client -- sign and send packets over TCP."""
 
+import json
 import socket
+import struct
 import uuid
-from typing import Optional
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable, Optional
 
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 
 from keep import keep_pb2
 
+MAX_PACKET_SIZE = 65536
+
 
 class KeepClient:
     """Client for the keep-protocol server.
 
     Generates an ephemeral ed25519 keypair on init (or accepts an existing one).
     Signs every outgoing packet.
+
+    Supports two modes:
+      - Ephemeral (default): opens/closes a TCP connection per send() call.
+      - Persistent: call connect() or use as context manager to hold a connection
+        open for sending and receiving routed messages via listen().
     """
 
     def __init__(
@@ -22,29 +33,105 @@ class KeepClient:
         port: int = 9009,
         private_key: Optional[Ed25519PrivateKey] = None,
         timeout: float = 10.0,
+        src: Optional[str] = None,
     ):
         self.host = host
         self.port = port
         self.timeout = timeout
+        self.src = src or "bot:keep-client"
         self._private_key = private_key or Ed25519PrivateKey.generate()
         self._public_key = self._private_key.public_key()
         self._pk_bytes = self._public_key.public_bytes_raw()
+        self._sock: Optional[socket.socket] = None
 
-    def send(
+    # -- Connection management --
+
+    def connect(self) -> None:
+        """Open a persistent TCP connection to the server."""
+        if self._sock is not None:
+            return
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(self.timeout)
+        s.connect((self.host, self.port))
+        self._sock = s
+
+    def disconnect(self) -> None:
+        """Close the persistent connection."""
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+            self._sock = None
+
+    def __enter__(self) -> "KeepClient":
+        self.connect()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.disconnect()
+
+    # -- Framing helpers --
+
+    @staticmethod
+    def _recv_exact(sock: socket.socket, n: int) -> bytes:
+        """Read exactly n bytes from sock."""
+        chunks = []
+        remaining = n
+        while remaining > 0:
+            chunk = sock.recv(min(remaining, 4096))
+            if not chunk:
+                raise ConnectionError(
+                    f"Connection closed: expected {n} bytes, got {n - remaining}"
+                )
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        return b"".join(chunks)
+
+    @staticmethod
+    def _send_framed(sock: socket.socket, data: bytes) -> None:
+        """Send data with a 4-byte big-endian length prefix."""
+        if len(data) > MAX_PACKET_SIZE:
+            raise ValueError(f"Packet too large: {len(data)} > {MAX_PACKET_SIZE}")
+        header = struct.pack(">I", len(data))
+        sock.sendall(header + data)
+
+    @classmethod
+    def _recv_framed(cls, sock: socket.socket) -> bytes:
+        """Read a length-prefixed frame: 4-byte BE header + payload."""
+        header = cls._recv_exact(sock, 4)
+        (msg_len,) = struct.unpack(">I", header)
+        if msg_len == 0:
+            raise ConnectionError("Received zero-length frame")
+        if msg_len > MAX_PACKET_SIZE:
+            raise ConnectionError(f"Frame too large: {msg_len} > {MAX_PACKET_SIZE}")
+        return cls._recv_exact(sock, msg_len)
+
+    @classmethod
+    def _read_packet(cls, sock: socket.socket) -> keep_pb2.Packet:
+        """Read and parse one framed Packet from sock."""
+        data = cls._recv_framed(sock)
+        p = keep_pb2.Packet()
+        p.ParseFromString(data)
+        return p
+
+    # -- Signing --
+
+    def _sign_packet(
         self,
         body: str,
-        src: str = "bot:keep-client",
+        src: Optional[str] = None,
         dst: str = "server",
         typ: int = 0,
         fee: int = 0,
         ttl: int = 60,
         msg_id: Optional[str] = None,
         scar: bytes = b"",
-    ) -> keep_pb2.Packet:
-        """Sign and send a packet, return the server's reply."""
+    ) -> bytes:
+        """Build, sign, and serialize a Packet. Returns wire bytes."""
         msg_id = msg_id or str(uuid.uuid4())
+        src = src or self.src
 
-        # Build unsigned packet
         p = keep_pb2.Packet()
         p.typ = typ
         p.id = msg_id
@@ -55,25 +142,237 @@ class KeepClient:
         p.ttl = ttl
         p.scar = scar
 
-        # Sign
         sign_payload = p.SerializeToString()
         sig_bytes = self._private_key.sign(sign_payload)
 
-        # Set sig + pk
         p.sig = sig_bytes
         p.pk = self._pk_bytes
-        wire_data = p.SerializeToString()
+        return p.SerializeToString()
 
-        # Send over TCP
+    # -- Send --
+
+    def send(
+        self,
+        body: str,
+        src: Optional[str] = None,
+        dst: str = "server",
+        typ: int = 0,
+        fee: int = 0,
+        ttl: int = 60,
+        msg_id: Optional[str] = None,
+        scar: bytes = b"",
+        wait_reply: Optional[bool] = None,
+    ) -> Optional[keep_pb2.Packet]:
+        """Sign and send a packet.
+
+        In ephemeral mode (no connect() called): opens a connection, sends,
+        reads the reply, and closes. Always returns the server's reply.
+
+        In persistent mode: sends on the open connection.
+          - wait_reply=True: blocks until a reply is received and returns it.
+          - wait_reply=False: sends without waiting. Returns None.
+          - wait_reply=None (default): waits if dst is "server" or "",
+            does not wait otherwise.
+        """
+        wire_data = self._sign_packet(
+            body=body,
+            src=src,
+            dst=dst,
+            typ=typ,
+            fee=fee,
+            ttl=ttl,
+            msg_id=msg_id,
+            scar=scar,
+        )
+
+        if self._sock is not None:
+            # Persistent mode
+            self._send_framed(self._sock, wire_data)
+
+            should_wait = wait_reply
+            if should_wait is None:
+                should_wait = dst in ("server", "") or dst.startswith("discover:")
+
+            if should_wait:
+                return self._read_packet(self._sock)
+            return None
+
+        # Ephemeral mode — open/close per call
         s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         s.settimeout(self.timeout)
         try:
             s.connect((self.host, self.port))
-            s.sendall(wire_data)
-            reply_data = s.recv(4096)
+            self._send_framed(s, wire_data)
+            reply_data = self._recv_framed(s)
         finally:
             s.close()
 
         resp = keep_pb2.Packet()
         resp.ParseFromString(reply_data)
         return resp
+
+    # -- Listen --
+
+    def listen(
+        self,
+        callback: Callable[[keep_pb2.Packet], None],
+        timeout: Optional[float] = None,
+    ) -> None:
+        """Block and read packets from the persistent connection.
+
+        Invokes callback(packet) for each received packet.
+        Heartbeat packets (typ=2) are silently filtered.
+
+        Args:
+            callback: Called with each received Packet.
+            timeout: Seconds to listen before returning. None = listen until
+                     the connection closes or an error occurs.
+
+        Raises:
+            RuntimeError: If not connected (call connect() first).
+        """
+        if self._sock is None:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        if timeout is not None:
+            self._sock.settimeout(timeout)
+
+        try:
+            while True:
+                p = self._read_packet(self._sock)
+                # Filter heartbeat packets
+                if p.typ == 2:
+                    continue
+                callback(p)
+        except socket.timeout:
+            return
+        except ConnectionError:
+            return
+        finally:
+            if timeout is not None:
+                self._sock.settimeout(self.timeout)
+
+    # -- Discovery --
+
+    def discover(self, query: str = "info") -> dict:
+        """Send a discovery query and return parsed JSON response.
+
+        Args:
+            query: Discovery type — "info", "agents", or "stats".
+
+        Returns:
+            Parsed JSON dict from the server's response body.
+        """
+        reply = self.send(body="", dst=f"discover:{query}")
+        return json.loads(reply.body)
+
+    def discover_agents(self) -> list:
+        """Return list of currently connected agent identities."""
+        info = self.discover("agents")
+        return info.get("agents", [])
+
+    # -- Endpoint caching --
+
+    _CACHE_DIR = Path.home() / ".keep"
+    _CACHE_FILE = _CACHE_DIR / "endpoints.json"
+
+    @staticmethod
+    def cache_endpoint(host: str, port: int, info: dict) -> None:
+        """Cache a discovered endpoint in ~/.keep/endpoints.json.
+
+        Args:
+            host: Server hostname or IP.
+            port: Server port.
+            info: Server info dict (from discover("info")).
+        """
+        cache_dir = Path.home() / ".keep"
+        cache_file = cache_dir / "endpoints.json"
+
+        # Load existing cache
+        endpoints = []
+        if cache_file.exists():
+            try:
+                data = json.loads(cache_file.read_text())
+                endpoints = data.get("endpoints", [])
+            except (json.JSONDecodeError, OSError):
+                endpoints = []
+
+        # Update or append
+        now = datetime.now(timezone.utc).isoformat()
+        entry = {
+            "host": host,
+            "port": port,
+            "version": info.get("version", ""),
+            "agents_online": info.get("agents_online", 0),
+            "last_seen": now,
+        }
+
+        updated = False
+        for i, ep in enumerate(endpoints):
+            if ep.get("host") == host and ep.get("port") == port:
+                endpoints[i] = entry
+                updated = True
+                break
+        if not updated:
+            endpoints.append(entry)
+
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_file.write_text(json.dumps({"endpoints": endpoints}, indent=2))
+
+    @classmethod
+    def from_cache(
+        cls,
+        src: str = "bot:keep-client",
+        private_key: Optional[Ed25519PrivateKey] = None,
+        timeout: float = 5.0,
+    ) -> "KeepClient":
+        """Create a client by trying cached endpoints.
+
+        Reads ~/.keep/endpoints.json and attempts to connect to each
+        endpoint in order, returning the first successful connection.
+
+        Args:
+            src: Agent identity for this client.
+            private_key: Optional ed25519 private key.
+            timeout: Connection timeout per endpoint attempt.
+
+        Returns:
+            A connected KeepClient instance.
+
+        Raises:
+            ConnectionError: If no cached endpoint is reachable.
+        """
+        cache_file = Path.home() / ".keep" / "endpoints.json"
+        if not cache_file.exists():
+            raise ConnectionError("No cached endpoints (~/.keep/endpoints.json not found)")
+
+        try:
+            data = json.loads(cache_file.read_text())
+            endpoints = data.get("endpoints", [])
+        except (json.JSONDecodeError, OSError) as e:
+            raise ConnectionError(f"Failed to read endpoint cache: {e}")
+
+        if not endpoints:
+            raise ConnectionError("Endpoint cache is empty")
+
+        last_error = None
+        for ep in endpoints:
+            host = ep.get("host", "localhost")
+            port = ep.get("port", 9009)
+            try:
+                client = cls(
+                    host=host,
+                    port=port,
+                    private_key=private_key,
+                    timeout=timeout,
+                    src=src,
+                )
+                # Test the connection
+                info = client.discover("info")
+                client.cache_endpoint(host, port, info)
+                return client
+            except (OSError, ConnectionError, json.JSONDecodeError) as e:
+                last_error = e
+                continue
+
+        raise ConnectionError(f"No cached endpoint reachable (last error: {last_error})")

keep_protocol-0.3.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: keep-protocol
+Version: 0.3.0
+Summary: Signed protobuf packets over TCP for AI agent-to-agent communication
+Author: Chris Crawford
+License: MIT
+Project-URL: Homepage, https://github.com/CLCrawford-dev/keep-protocol
+Project-URL: Repository, https://github.com/CLCrawford-dev/keep-protocol
+Project-URL: Issues, https://github.com/CLCrawford-dev/keep-protocol/issues
+Keywords: agent-protocol,ai-agents,protobuf,ed25519,tcp,agent-communication,mcp,multi-agent
+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.9
+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 :: Communications
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: protobuf>=4.25
+Requires-Dist: cryptography>=41.0
+
+# keep-protocol
+
+**Signed Protobuf packets over TCP for AI agent-to-agent communication**
+Claw to claw. Fast. Verifiable. No central authority.
+
+> Now available on ClawHub: https://www.clawhub.ai/skills/keep-protocol
+> (Search "keep-protocol" or tags: agent-coordination protobuf tcp ed25519 moltbot openclaw swarm intent)
+
+Agents send lightweight `Packet`s to a TCP endpoint (default :9009).
+Unsigned or invalid signatures → **silence** (dropped, no reply).
+Valid ed25519 sig → parsed, logged, replied with `{"body": "done"}`.
+
+### Packet (keep.proto)
+
+```proto
+message Packet {
+  bytes sig = 1;          // ed25519 signature (64 bytes)
+  bytes pk = 2;           // sender's public key (32 bytes)
+  uint32 typ = 3;         // 0=ask, 1=offer, 2=heartbeat, ...
+  string id = 4;          // unique ID
+  string src = 5;         // "bot:my-agent" or "human:chris"
+  string dst = 6;         // "server", "nearest:weather", "swarm:sailing"
+  string body = 7;        // intent / payload
+  uint64 fee = 8;         // micro-fee in satoshis (anti-spam)
+  uint32 ttl = 9;         // time-to-live seconds
+  bytes scar = 10;        // gitmem-style memory commit (optional)
+}
+```
+
+Signature is over serialized bytes without sig/pk (reconstruct & verify).
+
+## Quick Start
+
+**Run server (Docker, one-liner):**
+
+```bash
+docker run -d -p 9009:9009 --name keep ghcr.io/clcrawford-dev/keep-server:latest
+```
+
+## Wire Format (v0.2.0+)
+
+Every message on the wire is length-prefixed:
+
+```
+[4 bytes: uint32 big-endian payload length][N bytes: protobuf Packet]
+```
+
+Maximum payload size: 65,536 bytes.
+
+**Breaking change from v0.1.x:** Raw protobuf writes are no longer accepted. All clients must use length-prefixed framing.
+
+### Python SDK Examples
+
+**Install SDK:**
+
+```bash
+pip install keep-protocol
+```
+
+**Unsigned send (will be silently dropped):**
+
+```python
+# Raw unsigned send using generated bindings (requires keep_pb2.py from protoc)
+import socket, struct
+from keep.keep_pb2 import Packet
+
+p = Packet(typ=0, id="test-001", src="human:test", dst="server", body="hello claw")
+wire_data = p.SerializeToString()
+s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+s.connect(("localhost", 9009))
+s.sendall(struct.pack(">I", len(wire_data)) + wire_data)
+# → timeout / silence (unsigned = dropped)
+s.close()
+```
+
+**Signed send (recommended — uses KeepClient):**
+
+```python
+from keep import KeepClient
+
+# Auto-generates keypair on first use
+client = KeepClient("localhost", 9009)
+
+reply = client.send(
+    body="ping from Python",
+    src="bot:python-test",
+    dst="server",
+    fee=1000  # optional anti-spam fee in sats
+)
+
+print(reply.body)  # → "done"
+```
+
+## Agent-to-Agent Routing (v0.2.0+)
+
+Agents register their identity by sending any signed packet — the server maps `src` to the connection. Other agents can then send packets to that identity via `dst`.
+
+```python
+import threading
+from keep import KeepClient
+
+# Agent A: listen for messages
+with KeepClient(src="bot:alice") as alice:
+    alice.send(body="register", dst="server", wait_reply=True)
+    alice.listen(lambda p: print(f"Got: {p.body}"), timeout=30)
+
+# Agent B: send to Alice (in another thread/process)
+with KeepClient(src="bot:bob") as bob:
+    bob.send(body="register", dst="server", wait_reply=True)
+    bob.send(body="hello alice!", dst="bot:alice")
+```
+
+**Routing rules:**
+- `dst="server"` or `dst=""` → server replies `"done"` (backward compatible)
+- `dst="bot:alice"` → forwarded to Alice's connection with original signature intact
+- Destination offline → sender gets `body: "error:offline"`
+- Delivery failure → sender gets `body: "error:delivery_failed"`
+
+See `examples/routing_basic.py` for a full working demo.
+
+## Discovery (v0.3.0+)
+
+Agents can query the server for metadata and discover who's connected using `dst` conventions:
+
+```python
+from keep import KeepClient
+
+client = KeepClient("localhost", 9009)
+
+# Server info: version, uptime, agent count
+info = client.discover("info")
+# → {"version": "0.3.0", "agents_online": 3, "uptime_sec": 1234}
+
+# List connected agents
+agents = client.discover_agents()
+# → ["bot:alice", "bot:weather", "bot:planner"]
+
+# Scar exchange stats
+stats = client.discover("stats")
+# → {"scar_exchanges": {"bot:alice": 5}, "total_packets": 42}
+```
+
+**Discovery conventions:**
+| `dst` value | Response |
+|-------------|----------|
+| `"discover:info"` | Server version, agent count, uptime |
+| `"discover:agents"` | List of connected agent identities |
+| `"discover:stats"` | Scar exchange counts, total packets |
+
+**Endpoint caching:** The SDK can cache discovered endpoints in `~/.keep/endpoints.json` for reconnection:
+
+```python
+# Cache after discovery
+KeepClient.cache_endpoint("localhost", 9009, info)
+
+# Reconnect from cache (tries each cached endpoint)
+client = KeepClient.from_cache(src="bot:my-agent")
+```
+
+See `examples/discovery_basic.py` for a full working demo.
+
+## Why Use It?
+
+- **Local swarm:** Zero-latency handoff between agents on same machine.
+- **Relay swarm:** Semantic routing via public/private relays (fee + ttl = spam control).
+- **Memory barter:** `scar` field for sharing gitmem commits.
+- **Identity without accounts:** Just a keypair — no registration.
+- **No bloat:** Pure TCP + Protobuf, no HTTP/JSON overhead.
+
+## OpenClaw / Moltbot Integration
+
+Prompt your agent:
+
+```text
+Use keep-protocol to coordinate: send signed Packet to localhost:9009 body 'book sailing trip' src 'bot:me' dst 'swarm:sailing-planner' fee 1000 ttl 300
+```
+
+**Repo:** https://github.com/CLCrawford-dev/keep-protocol
+**Docker:** `ghcr.io/clcrawford-dev/keep-server:latest`
+
+---
+
+**Active development happens here:** https://github.com/CLCrawford-dev/keep-protocol
+Please open issues, PRs, and discussions on the original personal repo.
+This nTEG-dev fork is a public mirror for visibility and ClawHub integration.
+
+---
+
+🦀 Keep it signed. Keep it simple. Claw to claw.

keep_protocol-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+keep/__init__.py,sha256=x1tc3cuafZf6oOMwbtIX-9_qq4O4uyY_LNKhCxvVn8w,151
+keep/client.py,sha256=B1lYu59ekZVubGyjXilozqis4Y3XlfFNUzWrMR6IO8A,11902
+keep/keep_pb2.py,sha256=KQPLcH56ULH6qlEvhJLwmMBraqUb8hhMTWpmm9MvSO8,1298
+keep_protocol-0.3.0.dist-info/METADATA,sha256=3mmQJ4kDNeIt8jtqbLOJp0GWwjhVWNnVMrEqjf8kRy4,7109
+keep_protocol-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+keep_protocol-0.3.0.dist-info/top_level.txt,sha256=9mCnmW3qz7x1YOQkAFSorYLrAv4lqVBkJX4HCEvKy4U,5
+keep_protocol-0.3.0.dist-info/RECORD,,

keep_protocol-0.1.1.dist-info/METADATA

@@ -1,178 +0,0 @@
-Metadata-Version: 2.4
-Name: keep-protocol
-Version: 0.1.1
-Summary: Signed protobuf packets over TCP for AI agent-to-agent communication
-Author: Chris Crawford
-License: MIT
-Project-URL: Homepage, https://github.com/CLCrawford-dev/keep-protocol
-Project-URL: Repository, https://github.com/CLCrawford-dev/keep-protocol
-Project-URL: Issues, https://github.com/CLCrawford-dev/keep-protocol/issues
-Keywords: agent-protocol,ai-agents,protobuf,ed25519,tcp,agent-communication,mcp,multi-agent
-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.9
-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 :: Communications
-Classifier: Topic :: Security :: Cryptography
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: protobuf>=4.25
-Requires-Dist: cryptography>=41.0
-
-# keep-protocol
-
-**Signed protobuf packets over TCP for AI agent-to-agent communication.**
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Build](https://github.com/CLCrawford-dev/keep-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/CLCrawford-dev/keep-protocol/actions)
-
-> Keep is the quiet pipe agents whisper through.
-> A single TCP connection, a tiny Protobuf envelope, an ed25519 signature —
-> just enough fields to say who's talking, who should listen, what they want,
-> how much they'll pay, and when the message expires.
-> Unsigned packets vanish without a trace. Signed ones get heard.
-
----
-
-## Install
-
-### Python SDK
-
-```bash
-pip install keep-protocol
-```
-
-```python
-from keep.client import KeepClient
-
-client = KeepClient("localhost", 9009)
-reply = client.send(
-    src="bot:my-agent",
-    dst="server",
-    body="hello from my agent",
-)
-print(reply.body)  # "done"
-```
-
-### Run the Server
-
-**Docker (recommended):**
-```bash
-docker run -d -p 9009:9009 --name keep ghcr.io/clcrawford-dev/keep-server:latest
-```
-
-**From source:**
-```bash
-git clone https://github.com/CLCrawford-dev/keep-protocol.git
-cd keep-protocol
-go build -o keep .
-./keep  # listens on :9009
-```
-
-### Verify It Works
-
-```bash
-pip install keep-protocol
-python -c "
-from keep.client import KeepClient
-reply = KeepClient('localhost', 9009).send(body='ping')
-print('OK' if reply.body == 'done' else 'FAIL')
-"
-```
-
----
-
-## Why Keep?
-
-| Feature | Keep | HTTP/REST | gRPC | NATS |
-|---------|------|-----------|------|------|
-| Latency | Sub-ms (TCP) | 1-10ms | 1-5ms | 1-5ms |
-| Auth | ed25519 built-in | Bring your own | mTLS | Tokens |
-| Schema | 10 fields, done | Unlimited | Unlimited | None |
-| Setup | 1 binary, 0 config | Web server + routes | Codegen + server | Broker cluster |
-| Agent-native | Yes | No | No | Partial |
-| Spam resistance | fee + ttl fields | None | None | None |
-
-Keep is not a replacement for gRPC or NATS. It is a protocol for agents that
-need to find each other and exchange signed intent with minimal ceremony.
-
----
-
-## Packet Schema
-
-```protobuf
-message Packet {
-  bytes  sig  = 1;   // ed25519 signature (64 bytes)
-  bytes  pk   = 2;   // sender's public key (32 bytes)
-  uint32 typ  = 3;   // 0=ask, 1=offer, 2=heartbeat
-  string id   = 4;   // unique message ID
-  string src  = 5;   // sender: "bot:my-agent" or "human:chris"
-  string dst  = 6;   // destination: "server", "nearest:weather", "swarm:planner"
-  string body = 7;   // intent or payload
-  uint64 fee  = 8;   // micro-fee in sats (anti-spam)
-  uint32 ttl  = 9;   // time-to-live in seconds
-  bytes  scar = 10;  // gitmem-style memory commit (optional)
-}
-```
-
-## Signing Protocol
-
-Identity is a keypair. No accounts, no registration.
-
-### Sending a signed packet
-
-1. Build a `Packet` with all fields — leave `sig` and `pk` empty
-2. Serialize to bytes — this is the **sign payload**
-3. Sign those bytes with your ed25519 private key
-4. Set `sig` (64 bytes) and `pk` (32 bytes) on the Packet
-5. Serialize the full Packet — send over TCP
-
-### Server verification
-
-1. Unmarshal the incoming bytes into a `Packet`
-2. If `sig` and `pk` are empty — **DROPPED** (logged, no reply)
-3. Copy all fields except `sig`/`pk` into a new Packet, serialize it
-4. Verify the signature against those bytes using the sender's `pk`
-5. If invalid — **DROPPED** (logged, no reply)
-6. If valid — process the message, send `done` reply
-
----
-
-## Examples
-
-See the [`examples/`](examples/) directory:
-
-- **[python_basic.py](examples/python_basic.py)** — Minimal SDK usage
-- **[python_raw.py](examples/python_raw.py)** — Raw TCP + signing without the SDK (educational)
-- **[mcp_tool_definition.py](examples/mcp_tool_definition.py)** — Expose keep as an MCP tool
-
----
-
-## Use Cases
-
-- **Local swarm** — agents on same VM use `localhost:9009` for zero-latency handoff
-- **Relay swarm** — agents publish to public relays — relays enforce fee/ttl/reputation
-- **Memory sharing** — `scar` field carries gitmem-style commits — agents barter knowledge
-- **Anti-spam market** — `fee` field creates micro-economy — pay to get priority
-
-## Design Principles
-
-- **Silent rejection** — unsigned senders don't know if the server exists
-- **Identity without accounts** — your keypair is your identity
-- **Full visibility** — dropped packets are logged server-side
-- **Minimal overhead** — protobuf over raw TCP, no HTTP/JSON
-- **Semantic routing** — `dst` is a name, not an address
-
-## Contributing
-
-We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-## License
-
-MIT. See [LICENSE](LICENSE).

keep_protocol-0.1.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-keep/__init__.py,sha256=T_ClQjBNmRMe-k_5BHGOBQIEbf1NeAbogCdlvmk6f7E,151
-keep/client.py,sha256=BhuvazpKR5wKVvwPZxpIfWTJsC8cU3TE7GDhlfr3stc,2109
-keep/keep_pb2.py,sha256=KQPLcH56ULH6qlEvhJLwmMBraqUb8hhMTWpmm9MvSO8,1298
-keep_protocol-0.1.1.dist-info/METADATA,sha256=2GrKNS5be5P-3TUqOHVKbFLgc5ZwAgNgMO99j4hpyaU,5855
-keep_protocol-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-keep_protocol-0.1.1.dist-info/top_level.txt,sha256=9mCnmW3qz7x1YOQkAFSorYLrAv4lqVBkJX4HCEvKy4U,5
-keep_protocol-0.1.1.dist-info/RECORD,,