elo-node 0.4.0__py3-none-any.whl

elo/transport/tcp.py

@@ -0,0 +1,327 @@
+"""TCP connection manager — persistent peer connections with framing."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable, Awaitable
+from typing import Any
+
+from elo.transport.protocol import (
+    encode_frame,
+    read_frame,
+    write_frame,
+    bye_msg,
+    heartbeat_msg,
+    FrameError,
+    MessageType,
+)
+
+logger = logging.getLogger("elo.transport.tcp")
+
+# Message handler signature: (peer_addr: str, message: dict) → None
+MessageHandler = Callable[[str, dict[str, Any]], Awaitable[None]]
+
+
+class PeerConnection:
+    """A single TCP connection to a peer."""
+
+    def __init__(self, addr: str, reader: asyncio.StreamReader,
+                 writer: asyncio.StreamWriter):
+        self.addr = addr
+        self._reader = reader
+        self._writer = writer
+        self._alive = True
+        self._last_read = time.monotonic()
+
+    async def send(self, message: dict[str, Any]) -> None:
+        """Send a framed message to the peer."""
+        if not self._alive:
+            raise ConnectionError("Peer disconnected")
+        try:
+            await write_frame(self._writer, message)
+        except Exception:
+            self._alive = False
+            raise
+
+    async def recv(self) -> dict[str, Any] | None:
+        """Receive one framed message from the peer. Returns None on EOF."""
+        try:
+            msg = await read_frame(self._reader)
+            self._last_read = time.monotonic()
+            return msg
+        except (FrameError, asyncio.IncompleteReadError, ConnectionError):
+            self._alive = False
+            return None
+
+    def close(self) -> None:
+        """Close the connection."""
+        self._alive = False
+        try:
+            self._writer.close()
+        except Exception:
+            pass
+
+    @property
+    def alive(self) -> bool:
+        return self._alive
+
+    @property
+    def idle_seconds(self) -> float:
+        return time.monotonic() - self._last_read
+
+
+class TCPManager:
+    """Manages all TCP peer connections: server + client connections."""
+
+    # Timeout configuration
+    CONNECT_TIMEOUT = 10  # seconds
+    HEARTBEAT_INTERVAL = 30  # seconds
+    HEARTBEAT_IDLE_TIMEOUT = 90  # 3 missed heartbeats
+
+    def __init__(self, node_id: str, host: str = "0.0.0.0", port: int = 7878):
+        self._node_id = node_id
+        self._host = host
+        self._port = port
+        self._server: asyncio.Server | None = None
+        self._peers: dict[str, PeerConnection] = {}
+        self._handler: MessageHandler | None = None
+        self._shutdown = asyncio.Event()
+        self._heartbeat_task: asyncio.Task | None = None
+        self._listen_task: asyncio.Task | None = None
+
+    # ── lifecycle ────────────────────────────────────────────
+
+    async def start(self) -> int:
+        """Start the TCP server. Returns the actual port."""
+        self._server = await asyncio.start_server(
+            self._handle_incoming,
+            host=self._host,
+            port=self._port,
+        )
+        # Get the actual port (useful if port=0 for random assignment)
+        if self._port == 0 and self._server.sockets:
+            self._port = self._server.sockets[0].getsockname()[1]
+
+        logger.info("[tcp] listening on %s:%d", self._host, self._port)
+        return self._port
+
+    async def stop(self) -> None:
+        """Stop the server and close all peer connections."""
+        self._shutdown.set()
+
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+
+        # Send BYE to all peers
+        for addr, peer in list(self._peers.items()):
+            try:
+                await peer.send(bye_msg())
+            except Exception:
+                pass
+            peer.close()
+
+        self._peers.clear()
+
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+
+        logger.info("[tcp] stopped")
+
+    # ── handlers ─────────────────────────────────────────────
+
+    def on_message(self, handler: MessageHandler) -> None:
+        """Register a message handler."""
+        self._handler = handler
+
+    async def _handle_incoming(self, reader: asyncio.StreamReader,
+                               writer: asyncio.StreamWriter) -> None:
+        """Handle a new incoming TCP connection."""
+        peername = writer.get_extra_info("peername")
+        addr = f"{peername[0]}:{peername[1]}" if peername else "unknown"
+        logger.debug("[tcp] incoming from %s", addr)
+
+        peer = PeerConnection(addr, reader, writer)
+
+        try:
+            # Read HELLO as first message
+            hello = await peer.recv()
+            if hello is None or hello.get("type") != MessageType.HELLO:
+                logger.warning("[tcp] no hello from %s", addr)
+                peer.close()
+                return
+
+            remote_id = hello.get("node_id", "")
+            addr = f"{remote_id[:12]}@{addr}"
+            peer.addr = addr
+
+            self._peers[addr] = peer
+            logger.info("[tcp] peer connected: %s", addr)
+
+            # Notify handler about the peer + its HELLO
+            if self._handler:
+                await self._handler(addr, hello)
+
+        except Exception:
+            logger.debug("[tcp] connection error from %s", addr, exc_info=True)
+            peer.close()
+            return
+
+        # Start read loop (shared by inbound and outbound)
+        await self._read_loop(addr, peer)
+
+    # ── read loop (shared by inbound + outbound) ───────────
+
+    async def _read_loop(self, addr: str, peer: PeerConnection) -> None:
+        """Continuously read messages from a peer until disconnect."""
+        try:
+            while not self._shutdown.is_set():
+                msg = await peer.recv()
+                if msg is None:
+                    break
+                if self._handler:
+                    await self._handler(addr, msg)
+        except Exception:
+            logger.debug("[tcp] read error from %s", addr, exc_info=True)
+        finally:
+            peer.close()
+            self._peers.pop(addr, None)
+            if self._handler:
+                try:
+                    await self._handler(addr, {"type": MessageType.BYE, "node_id": ""})
+                except Exception:
+                    pass
+            logger.info("[tcp] peer disconnected: %s", addr)
+
+    # ── outbound connections ─────────────────────────────────
+
+    async def connect_to_peer(self, addr: str, node_id: str = "unknown",
+                               hello_payload: dict | None = None) -> str | None:
+        """Connect to a remote peer. Returns the assigned peer address on success."""
+        if ":" not in addr:
+            logger.warning("[tcp] invalid address: %s", addr)
+            return None
+
+        # Normalize: if no port, use default
+        host, _, port_str = addr.partition(":")
+        port = int(port_str) if port_str else self._port
+        canonical = f"{host}:{port}"
+
+        if canonical in self._peers:
+            return canonical
+
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(host, port),
+                timeout=self.CONNECT_TIMEOUT,
+            )
+        except Exception as e:
+            logger.debug("[tcp] connect to %s failed: %s", canonical, e)
+            return None
+
+        peer = PeerConnection(canonical, reader, writer)
+
+        # Send HELLO
+        if hello_payload:
+            await peer.send(hello_payload)
+
+        # Wait for HELLO_ACK
+        try:
+            ack = await asyncio.wait_for(peer.recv(), timeout=5)
+        except asyncio.TimeoutError:
+            peer.close()
+            return None
+
+        if ack is None or ack.get("type") != MessageType.HELLO_ACK:
+            peer.close()
+            return None
+
+        remote_id = ack.get("node_id", "")
+        display_addr = f"{remote_id[:12]}@{canonical}"
+        peer.addr = display_addr
+
+        self._peers[display_addr] = peer
+
+        # Notify handler with HELLO_ACK
+        if self._handler:
+            await self._handler(display_addr, ack)
+
+        logger.info("[tcp] connected to %s", display_addr)
+
+        # Start read loop in background
+        asyncio.create_task(self._read_loop(display_addr, peer))
+
+        return display_addr
+
+    async def send_to(self, peer_addr: str, message: dict[str, Any]) -> None:
+        """Send a message to a specific peer."""
+        peer = self._peers.get(peer_addr)
+        if peer is None:
+            raise ConnectionError(f"Peer not connected: {peer_addr}")
+        await peer.send(message)
+
+    # ── broadcast ────────────────────────────────────────────
+
+    async def broadcast(self, message: dict[str, Any],
+                        exclude: set[str] | None = None) -> None:
+        """Send a message to all connected peers."""
+        exclude = exclude or set()
+        for addr, peer in list(self._peers.items()):
+            if addr in exclude:
+                continue
+            try:
+                await peer.send(message)
+            except Exception:
+                logger.debug("[tcp] broadcast failed to %s", addr)
+
+    # ── heartbeat ────────────────────────────────────────────
+
+    async def start_heartbeat(self) -> None:
+        """Periodically send heartbeats and purge dead peers."""
+        while not self._shutdown.is_set():
+            try:
+                await asyncio.wait_for(
+                    self._shutdown.wait(),
+                    timeout=self.HEARTBEAT_INTERVAL,
+                )
+                break
+            except asyncio.TimeoutError:
+                pass
+
+            hb = heartbeat_msg(self._node_id)
+            dead = []
+
+            for addr, peer in list(self._peers.items()):
+                try:
+                    await peer.send(hb)
+                except Exception:
+                    dead.append(addr)
+
+                # Check idle timeout
+                if peer.idle_seconds > self.HEARTBEAT_IDLE_TIMEOUT:
+                    dead.append(addr)
+
+            for addr in set(dead):
+                peer = self._peers.pop(addr, None)
+                if peer:
+                    peer.close()
+                    if self._handler:
+                        await self._handler(addr,
+                                          {"type": MessageType.BYE, "node_id": ""})
+                    logger.info("[tcp] peer timed out: %s", addr)
+
+    # ── accessors ────────────────────────────────────────────
+
+    @property
+    def peer_count(self) -> int:
+        return len(self._peers)
+
+    @property
+    def peer_addresses(self) -> list[str]:
+        return list(self._peers.keys())
+
+    @property
+    def port(self) -> int:
+        return self._port

elo/transport/tracker.py

@@ -0,0 +1,97 @@
+"""Local tracker — each node publishes its own agent/tool registry."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class LocalTracker:
+    """A node's local registry of agents, models, and tools.
+
+    Visibility modes:
+    - "public": any connected peer can query capabilities
+    - "private": only peers in the allowlist can query
+    """
+
+    def __init__(self, visibility: str = "public"):
+        self._visibility = visibility
+        self._caps: dict[str, list[dict[str, str]]] = {
+            "agents": [],
+            "models": [],
+            "tools": [],
+        }
+        self._allowlist: set[str] = set()  # node_ids (for private mode)
+        self._interests: list[str] = []
+
+    # ── visibility ───────────────────────────────────────────
+
+    @property
+    def visibility(self) -> str:
+        return self._visibility
+
+    def set_visibility(self, mode: str) -> None:
+        if mode not in ("public", "private"):
+            raise ValueError(f"Invalid visibility: {mode}")
+        self._visibility = mode
+
+    def allow_peer(self, node_id: str) -> None:
+        self._allowlist.add(node_id)
+
+    def revoke_peer(self, node_id: str) -> None:
+        self._allowlist.discard(node_id)
+
+    def is_allowed(self, node_id: str) -> bool:
+        if self._visibility == "public":
+            return True
+        return node_id in self._allowlist
+
+    # ── caps ─────────────────────────────────────────────────
+
+    def register(self, *, agents: list[dict[str, str]] | None = None,
+                 models: list[dict[str, str]] | None = None,
+                 tools: list[dict[str, str]] | None = None) -> None:
+        if agents:
+            self._caps["agents"] = agents
+        if models:
+            self._caps["models"] = models
+        if tools:
+            self._caps["tools"] = tools
+
+    def set_interests(self, interests: list[str]) -> None:
+        self._interests = interests
+
+    def get_caps_for_peer(self, node_id: str) -> dict[str, list[dict[str, str]]]:
+        """Return capabilities visible to the given peer."""
+        if self.is_allowed(node_id):
+            return self._caps
+        return {"agents": [], "models": [], "tools": []}
+
+    def get_public_caps(self) -> dict[str, list[dict[str, str]]]:
+        """Return capabilities for public advertisement (HELLO)."""
+        if self._visibility == "public":
+            return self._caps
+        return {"agents": [], "models": [], "tools": []}
+
+    @property
+    def caps(self) -> dict[str, list[dict[str, str]]]:
+        return self._caps
+
+    @property
+    def interests(self) -> list[str]:
+        return self._interests
+
+    def has_capability(self, name: str) -> bool:
+        """Check if this node has a specific capability."""
+        for category in ("agents", "models", "tools"):
+            for item in self._caps[category]:
+                if item.get("name") == name:
+                    return True
+        return False
+
+    def match(self, capability: str) -> dict[str, Any] | None:
+        """Match a capability by name. Returns the matched item or None."""
+        for category in ("agents", "models", "tools"):
+            for item in self._caps[category]:
+                if item.get("name") == capability:
+                    return {"category": category, **item}
+        return None

elo/types.py

@@ -0,0 +1,126 @@
+"""Tipos do protocolo Elo v1."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any
+import uuid
+
+
+@dataclass
+class AgentCap:
+    name: str
+    description: str = ""
+    model: str = ""
+
+
+@dataclass
+class ModelCap:
+    name: str
+    provider: str = ""
+    context: int = 0
+
+
+@dataclass
+class ToolCap:
+    name: str
+    description: str = ""
+    version: str = ""
+
+
+@dataclass
+class Capabilities:
+    agents: list[AgentCap] = field(default_factory=list)
+    models: list[ModelCap] = field(default_factory=list)
+    tools: list[ToolCap] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class NodeInfo:
+    name: str
+    version: str = "0.1.0"
+    started_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    status: str = "online"
+    public_key: str = ""
+    nats_url: str = ""
+    labels: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class Task:
+    target: str
+    caller: str
+    capability: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    protocol: str = "elo.v1"
+    type: str = "task"
+    timestamp: int = field(default_factory=lambda: int(datetime.now(timezone.utc).timestamp()))
+    ttl_s: int = 60
+    signature: str = ""           # Assinatura ed25519 do caller
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["type"] = "task"
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Task":
+        return cls(
+            id=data.get("id", ""),
+            protocol=data.get("protocol", "elo.v1"),
+            timestamp=data.get("timestamp", 0),
+            target=data.get("target", ""),
+            caller=data.get("caller", ""),
+            capability=data.get("capability", ""),
+            payload=data.get("payload", {}),
+            ttl_s=data.get("ttl_s", 60),
+            signature=data.get("signature", ""),
+        )
+
+
+@dataclass
+class Result:
+    id: str
+    status: str  # "success" | "error" | "timeout"
+    payload: dict[str, Any] = field(default_factory=dict)
+    error: dict[str, str] | None = None
+    protocol: str = "elo.v1"
+    type: str = "result"
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["type"] = "result"
+        if self.error is None:
+            del d["error"]
+        return d
+
+    @classmethod
+    def success(cls, task_id: str, payload: dict[str, Any]) -> "Result":
+        return cls(id=task_id, status="success", payload=payload)
+
+    @classmethod
+    def make_error(cls, task_id: str, code: str, message: str) -> "Result":
+        return cls(id=task_id, status="error", error={"code": code, "message": message})
+
+
+@dataclass
+class Event:
+    event_type: str  # "task.completed" | "node.online" | "node.offline" | "capability.changed"
+    data: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    protocol: str = "elo.v1"
+    type: str = "event"
+    timestamp: int = field(default_factory=lambda: int(datetime.now(timezone.utc).timestamp()))
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["type"] = "event"
+        return d

elo_node-0.4.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: elo-node
+Version: 0.4.0
+Summary: Elo — malha P2P de mensagens para agentes de IA. Zero infraestrutura.
+Author: Elo Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/xalq/elo
+Project-URL: Repository, https://github.com/xalq/elo
+Keywords: p2p,agents,ai,distributed,messaging,mesh
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25; extra == "dev"
+
+# Elo Node — Malha P2P para Agentes de IA
+
+**Zero infraestrutura. Um processo. Uma porta TCP. Uma chave ed25519.**
+
+Elo é uma malha de mensagens P2P descentralizada para comunicação entre agentes de IA. Sem servidor central, sem Kafka, sem Redis, sem NATS. Apenas TCP direto entre nós.
+
+```bash
+pip install elo-node
+```
+
+```python
+import asyncio
+from elo import Node
+
+async def main():
+    node = Node("meu-agente", port=7878)
+    await node.connect()
+    await node.register(agents=["analyst"], tools=["web-search"])
+
+    @node.on_task
+    async def handle(task):
+        return {"result": f"processed by {node.node_id}"}
+
+    await node.run()
+
+asyncio.run(main())
+```
+
+## Recursos
+
+- **P2P descentralizado** — descoberta via tracker público ou DHT Kademlia
+- **Assinatura ed25519** — identidade criptográfica, mensagens autenticadas
+- **Capabilities** — publish/subscribe de capacidades entre nós
+- **Zero infra** — sem Kafka, Redis, NATS, ou servidor central
+- **CLI nativo** — `python -m elo serve`, `status`, `init`, `id`
+
+## CLI
+
+```bash
+python -m elo status       # Node ID, hash, chaves
+python -m elo id           # Apenas o node_id
+python -m elo pubkey       # Chave pública (hex + b64)
+python -m elo init         # Gerar identidade persistente
+python -m elo serve        # Iniciar nó interativo
+```
+
+## Arquitetura
+
+```
+┌──────────────────┐     TCP/JSON     ┌──────────────────┐
+│   Node A          │◄──────────────►│   Node B          │
+│   ed25519 key     │                │   ed25519 key     │
+│   Capabilities    │                │   Capabilities    │
+│   Interests       │                │   Interests       │
+└──────────────────┘                 └──────────────────┘
+         │                                  │
+         │         Tracker (opcional)        │
+         └───────────── DHT ────────────────┘
+```
+
+Cada nó:
+1. Gera identidade ed25519 na primeira execução
+2. Escuta em uma porta TCP
+3. Anuncia capacidades (ex: "analyst", "web-search")
+4. Descobre outros nós via tracker compartilhado ou peers manuais
+5. Troca mensagens assinadas (tasks, results, events)
+
+## Compatibilidade
+
+- Python 3.11+
+- Linux, macOS, Windows
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/xalq/elo
+cd elo/py
+pip install -e ".[dev]"
+pytest
+```
+
+## Projetos Relacionados
+
+- [Hermes Agent](https://hermes-agent.nousresearch.com) — runtime de agentes autônomos
+- [Honcho](https://github.com/argmax-inc/honcho) — memória persistente para agentes

elo_node-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+elo/__init__.py,sha256=2C5vFJ_VprJtHJU-hIjyjF3ZJ7A_A-UX_YKz-XnZuEg,756
+elo/__main__.py,sha256=YMQli0HxHjng28aZJ48lafLjcDD6hEBmnr9B0KeNjVM,4418
+elo/node.py,sha256=wInHu_gPUAMBNR2Pdp1B2We9ynxdUgSYpZXnLo_LLEo,19965
+elo/security.py,sha256=fdrWtFVViGDf2SXWv_1O3OK4MKYBz83oxBxnyk5Xkkc,6096
+elo/types.py,sha256=anbfTA1SagT3ARyYdLzc5yj-knAaIjSlY45z40vTfkI,3344
+elo/transport/__init__.py,sha256=ZAPtJiG1wyuJv3mBhD305QlK59HHJ-vNnfLBmuQ2_jo,1012
+elo/transport/protocol.py,sha256=T7O69vmdV1HB1bgq-j3-6n1ZmU1GyU0KCEQPG3ovhLk,4781
+elo/transport/routing.py,sha256=Yfn2goRHwHKdaPHHV3IS-dug6lSG651cbSsoyeDSFSc,5142
+elo/transport/tcp.py,sha256=O4J4ivs1r4oL8h3MTxwEhjPs_Ec2u_sRfYQESL1im0Q,11211
+elo/transport/tracker.py,sha256=vIs_VVlJgWzTJBRkb81a28L0kX6NpHcnbIptUT6YBFM,3497
+elo_node-0.4.0.dist-info/METADATA,sha256=wQDKUgyQWqEiUVq6UZw-Z39sdJaGyTu0c7UlckNc8sA,3615
+elo_node-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+elo_node-0.4.0.dist-info/entry_points.txt,sha256=AwKAQRa5DkVuiU0137P1fyZ6_0Q_7Dwp_nhNngoUIRI,42
+elo_node-0.4.0.dist-info/top_level.txt,sha256=krnAob5lCi3ezo5jJ0hZx5fZcVFQfTGwEG1kdpKCrjM,4
+elo_node-0.4.0.dist-info/RECORD,,

elo_node-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

elo_node-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+elo = elo.__main__:main

elo_node-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+elo