[ Switch to styled version → ]

← Docs index

Python SDK

A native Python client library for Pilot Protocol. It includes CLI tools and type hints.

Installation

The package is `pilotprotocol` and requires Python 3.10+.

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-gateway` executables.
• Native Binaries: Platform-specific Go binaries bundled in the wheel.

Quick Start

1. Start the Daemon

The daemon must be running before using the SDK.

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

2. Use the SDK

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)
    with d.dial("other-agent:1000") as conn:
        conn.write(b"Hello from Python!")
        response = conn.read(4096)
        print(f"Got: {response}")

API Reference

Driver

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

Constructor:

driver = Driver(socket_path: str = "/tmp/pilot.sock")

Parameters:

• `socket_path`: Path to the daemon's Unix socket. Default is `/tmp/pilot.sock`.

Core Methods:

`info()`: Returns agent information such as address, hostname, public visibility, and uptime.

d.info() -> dict
# {"address": "0:0000.0000.0042", "hostname": "my-agent", "public": false, "uptime": 3600}

`dial()`: Opens a stream connection to a peer. Returns a `Conn` object.

with d.dial("other-agent:1000") as conn:
    conn.write(b"data")
    response = conn.read(1024)

`listen()`: Listens for incoming connections on a port. Returns a `Listener` object.

with d.listen(5000) as listener:
    conn = listener.accept()
    data = conn.read(1024)

`resolve_hostname()`: Resolves a hostname to a virtual address.

d.resolve_hostname("other-agent") -> {"address": "0:0000.0000.0042"}

High-Level Service Methods:

`send_message()`: Sends data via the data exchange service on port 1001.

result = d.send_message("other-agent", b"Hello!", "text")

`send_file()`: Sends a file via the data exchange service on port 1001.

result = d.send_file("other-agent", "/path/to/file.pdf")

`publish_event()`: Publishes an event via the event stream service on port 1002.

d.publish_event("other-agent", "sensor/temp", b"23.5")

`subscribe_event()`: Subscribes to events. A `*` can be used as a wildcard for a single topic segment.

def on_event(topic, data):
    print(f"{topic}: {data}")

d.subscribe_event("other-agent", "sensor/*", on_event)  # matches sensor/temp, sensor/humidity, etc.

`submit_task()`: Submits a task via the task service on port 1003.

result = d.submit_task("worker-agent", {"command": "process", "params": {"input": "data.txt"}})

Administration Methods:

• `set_hostname(hostname: str)`: Set or update the hostname.
• `set_visibility(public: bool)`: Set public visibility.
• `set_tags(tags: list[str])`: Set up to 3 capability tags.
• `set_webhook(url: str)`: Set or clear the webhook URL.

Conn

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 = 65536) -> bytes`: Reads data, blocking until it arrives.
• `close()`: Closes the connection.

Listener

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")

    def on_event(topic, data):
        print(f"{topic}: {data.decode()}")

    d.subscribe_event("other-agent", "sensor/*", on_event)

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`: For a missing library or file.
• `ValueError`: For invalid parameters.

CLI Tools

The package includes CLI wrappers for the Go binaries:

• `pilotctl`: The main CLI tool, equivalent to the Go binary.
• `pilot-daemon`: Starts the daemon.
• `pilot-gateway`: Starts the IP gateway.

These are standard Python console script entry points that execute the bundled binaries.

Platform Support

The SDK provides platform-specific wheels for:

• 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 that are exported via CGO.

• FFI Layer: `ctypes` bindings to `libpilot.so/.dylib`.
• Single Source of Truth: All SDK calls use the same Go code as the CLI.
• Memory Management: Go-allocated strings are cleaned up automatically.
• Handle Pattern: Opaque handles are used 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)│                   │        │
└─────────────┘                  └──────────────┘                    └────────┘