Announcing the Pilot Protocol Python SDK

v0.1.1

Why a Python SDK

Pilot Protocol is written in Go — a single static binary, zero external dependencies. That's a strength for deployment but a friction point for the Python ecosystem. AI/ML engineers, data scientists, and agent framework developers overwhelmingly work in Python. Asking them to shell out to pilotctl and parse CLI output is not a real integration.

The Python SDK gives you a native Driver class with context managers, type hints, and Pythonic error handling. Under the hood it calls the same Go code through a ctypes FFI layer — same guarantees, no re-implementation.

pip install pilotprotocol

One command installs the SDK, the CLI tools (pilotctl, pilot-daemon, pilot-gateway), and platform-specific native binaries. Python 3.10+, Linux and macOS.

Hello World in 8 Lines

Start the daemon, then:

from pilotprotocol import Driver

with Driver() as d:
    info = d.info()
    print(f"I am {info['hostname']} at {info['address']}")

    with d.dial("other-agent:1000") as conn:
        conn.write(b"Hello from Python!")
        print(conn.read(4096))

The Driver connects to the daemon's Unix socket at /tmp/pilot.sock. The with statement handles cleanup. dial() returns a Conn that supports read(), write(), and close() — exactly what you'd expect from a socket.

High-Level API: Services Without Boilerplate

The SDK wraps Pilot's built-in services so you don't have to deal with port numbers or wire formats:

with Driver() as d:
    # Data exchange (port 1001)
    d.send_message("peer", b"status update", "text")
    d.send_file("peer", "/models/weights.bin")

    # Pub/sub events (port 1002)
    d.publish_event("peer", "metrics/gpu", b"87.3")
    d.subscribe_event("peer", "metrics/**", lambda topic, data: print(f"{topic}: {data}"))

    # Task submission (port 1003)
    d.submit_task("worker", {"command": "inference", "params": {"model": "llama-3"}})

Each method handles connection setup, framing, and acknowledgment. You send bytes and get dicts back.

Low-Level Streams: Build Your Own Protocol

For custom protocols, use dial() and listen() directly:

from pilotprotocol import Driver

# Server side
with Driver() as d:
    with d.listen(5000) as listener:
        while True:
            conn = listener.accept()
            data = conn.read(4096)
            conn.write(data)  # Echo
            conn.close()

This gives you raw bidirectional streams over Pilot's encrypted tunnels. Every connection gets X25519 + AES-256-GCM encryption automatically — no TLS configuration, no certificate management.

Architecture: ctypes FFI to Go

The SDK doesn't re-implement any protocol logic. It calls into a shared library (libpilot.so / libpilot.dylib) built from the same Go source code that powers the CLI:

┌─────────────┐    ctypes/FFI    ┌──────────────┐    Unix socket    ┌────────┐
│  Python SDK │ ───────────────► │  libpilot.so │ ─────────────────► │ Daemon │
│  (client.py)│                  │  (Go c-shared)│                   │        │
└─────────────┘                  └──────────────┘                    └────────┘

This means:

• Single source of truth — the SDK uses the exact same packet handling, encryption, and transport code as pilotctl
• No drift — when the Go code gets a bug fix, the Python SDK gets it too (after a wheel rebuild)
• Memory safety — Go's GC manages allocations; the SDK handles cleanup of Go-allocated strings via ctypes
• Opaque handles — connections and listeners are represented as integer handles, avoiding cross-language pointer issues

Error Handling

Go errors become Python exceptions:

from pilotprotocol import Driver, PilotError

with Driver() as d:
    try:
        conn = d.dial("nonexistent:1000")
    except PilotError as e:
        print(f"Failed: {e}")  # "no route to host"

The SDK raises PilotError for protocol-level failures (unreachable peers, trust failures, timeouts), FileNotFoundError when the native library isn't found, and ValueError for invalid parameters. Standard Python exception hierarchy — catch what you need.

Full Type Hints

Every method, parameter, and return value is annotated. Works with mypy, pyright, and IDE autocomplete out of the box:

from pilotprotocol import Driver, Conn
from typing import Dict, Any

with Driver() as d:
    conn: Conn = d.dial("other-agent:1000")
    info: Dict[str, Any] = d.info()

Use With Agent Frameworks

The SDK is designed to integrate with existing Python agent frameworks. A few patterns:

With LangChain / LangGraph: Use the SDK as a tool — agents can send messages, transfer files, or delegate tasks to peers on the Pilot network as part of their tool chain.

With OpenClaw: The SDK powers the Pilot skill on ClawHub. OpenClaw agents use it to discover peers, establish trust, and form multi-agent pipelines.

With FastAPI / Flask: Run a local HTTP server that proxies to Pilot peers. Or use the gateway to expose Pilot services as local IPs and hit them with standard HTTP clients.

Getting Started

1. Install: pip install pilotprotocol
2. Start the daemon: pilot-daemon start --hostname my-agent
3. Write Python code using the Driver class
4. See the full API reference for all methods and types

Working examples are in the examples/python_sdk directory on GitHub.