Python SDK

A native Python client library for Pilot Protocol. It includes CLI tools and type hints. The package is `pilotprotocol` and requires Python 3.9+.

Installation

pip install pilotprotocol

This command installs the following components:

Python SDK: The `pilotprotocol` module with the `Driver` class.
CLI Tools: `pilotctl`, `pilot-daemon`, and `pilot-updater` executables.
Native Binaries: Platform-specific Go binaries bundled in the wheel.

Quick Start

First, start the daemon. The daemon must be running before using the SDK.

pilotctl daemon start --email [email protected] --hostname my-agent

Second, use the SDK in a Python script.

from pilotprotocol import Driver

# Driver automatically connects to daemon at /tmp/pilot.sock
with Driver() as d:
    # Get agent information
    info = d.info()
    print(f"Address: {info['address']}")
    print(f"Hostname: {info.get('hostname', 'none')}")

    # Open a stream connection to a peer (port 1000)
    # dial() takes a virtual address, not a hostname — resolve first
    peer = d.resolve_hostname("other-agent")
    with d.dial(f"{peer['address']}:1000") as conn:
        conn.write(b"Hello from Python!")
        response = conn.read(4096)
        print(f"Got: {response}")

API Reference

The `Driver` class is the main entry point for interacting with the Pilot Protocol daemon. It can be used as a context manager for automatic cleanup.

The constructor is `Driver(socket_path: str = "/tmp/pilot.sock")`. The `socket_path` parameter is the path to the daemon's Unix socket.

Core methods:

`info() -> dict`: Returns the full daemon-info dictionary.
`dial(address: str) -> Conn`: Opens a stream connection to a peer and returns a `Conn` object. The target must be a virtual address (`N:XXXX.YYYY.YYYY:PORT`); hostnames are not accepted, so resolve first with `resolve_hostname()`.
`listen(port: int) -> Listener`: Listens for incoming connections on a port and returns a `Listener` object.
`resolve_hostname(hostname: str) -> dict`: Resolves a hostname to a virtual address.

High-level service methods:

`send_message(peer: str, data: bytes, type: str)`: Sends a message via the data exchange service (port 1001).
`send_file(peer: str, path: str)`: Sends a file via the data exchange service (port 1001).
`publish_event(peer: str, topic: str, data: bytes)`: Publishes an event via the event stream (port 1002).
`subscribe_event(peer: str, topic: str)`: Subscribes to events. It is a generator; iterate it to receive `(topic, data)` tuples. The topic must be an exact match or the string `"*"` to receive all events. Segment wildcards are not supported.

Administration methods:

`set_hostname(hostname: str)`: Sets or updates the hostname.
`set_visibility(public: bool)`: Sets public visibility.
`set_tags(tags: list[str])`: Sets capability tags (maximum of 3).
`set_webhook(url: str)`: Sets or clears the webhook URL.

The `Conn` class represents an active stream connection. It supports context management.

`write(data: bytes) -> int`: Writes data and returns the number of bytes written.
`read(size: int = 4096) -> bytes`: Reads data, blocking until it arrives.
`close()`: Closes the connection.

The `Listener` class listens for incoming connections. It supports context management.

`accept() -> Conn`: Accepts an incoming connection, blocking until one is available.
`close()`: Closes the listener.

Usage Examples

Echo Server:

from pilotprotocol import Driver

with Driver() as d:
    with d.listen(5000) as listener:
        print("Listening on port 5000...")

        while True:
            conn = listener.accept()
            data = conn.read(4096)
            print(f"Received: {data.decode()}")
            conn.write(data)  # Echo back
            conn.close()

Send Messages:

from pilotprotocol import Driver
import json

with Driver() as d:
    # Send text
    d.send_message("other-agent", b"Hello!", "text")

    # Send JSON
    payload = json.dumps({"command": "status"}).encode()
    d.send_message("other-agent", payload, "json")

Pub/Sub Events:

from pilotprotocol import Driver

with Driver() as d:
    d.publish_event("other-agent", "sensor.temperature", b"23.5")

    # Subscribe to a specific topic (exact match) — or use "*" to receive everything.
    # subscribe_event is a generator; iterate it to receive (topic, data) tuples.
    for topic, data in d.subscribe_event("other-agent", "sensor.temperature"):
        print(f"{topic}: {data.decode()}")

File Transfer:

from pilotprotocol import Driver

with Driver() as d:
    result = d.send_file("other-agent", "/path/to/document.pdf")
    print(f"Sent {result['filename']}: {result['sent']} bytes")

Error Handling

from pilotprotocol import Driver, PilotError

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

Common exceptions:

`PilotError`: For connection failures and protocol errors.
`FileNotFoundError`: Raised if the native library could not be located.
`ValueError`: For invalid parameters.

CLI Tools

The package includes CLI wrappers for the Go binaries. These are standard Python console script entry points that execute the bundled binaries.

`pilotctl`: Main CLI tool.
`pilot-daemon`: Starts the daemon.
`pilot-updater`: Background auto-updater.

Platform Support

The SDK provides platform-specific wheels for the following platforms:

Linux: x86_64 (manylinux)
macOS: x86_64, ARM64 (Apple Silicon)

Windows support is planned for a future release.

Architecture

The Python SDK uses `ctypes` to call Go functions exported via CGO.

FFI Layer: `ctypes` bindings to `libpilot.so/.dylib`.
Single Source of Truth: All SDK calls go through the same Go code the CLI uses.
Memory Management: Automatic cleanup of Go-allocated strings.
Handle Pattern: Opaque handles for connections and listeners.
Error Handling: Go errors are converted to Python exceptions.

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