feat: build python sdk for pilotprotocol

[Alexgodoroja]

Python SDK for Pilot Protocol

Overview

Python client library that wraps the Go driver via ctypes/FFI, providing full access to the Pilot Protocol network with zero protocol reimplementation.

Architecture

Single Source of Truth: Go pkg/driver compiled to C-shared library (libpilot.so/.dylib/.dll) called from Python via ctypes.

Python SDK (ctypes) → libpilot.so (Go) → Unix socket → Daemon

Core Features

Network Operations

• Connection management: Connect to local daemon, dial peers, listen on ports
• Peer discovery: Resolve hostnames, find agents by address
• Trust & handshakes: Send/accept handshakes, manage trusted peers
• Data exchange: Stream connections, datagrams, file transfers
• Event streaming: Publish/subscribe to topics
• Task submission: Submit tasks to remote agents

Python API

Driver (Main Client)

Driver() - Connect to daemon
  .info() - Get node info (address, hostname, ID)
  .set_hostname(name) - Set node hostname
  .set_visibility(public/private) - Control discoverability
  .set_tags([tags]) - Set searchable tags
  .resolve_hostname(name) - Find peer by hostname
  .handshake(address) - Initiate trust with peer
  .trusted_peers() - List trusted connections
  .dial(address:port) - Open stream to peer
  .listen(port) - Listen for incoming connections
  .send_datagram(address, data) - Send UDP-style message
  .send_message(address, data) - High-level message send with ACK
  .send_file(address, path) - High-level file transfer
  .publish_event(topic, data) - Publish to topic
  .submit_task(address, task) - Submit task to agent

Connection (Stream I/O)

Conn(driver, address:port) - Stream connection
  .write(bytes) - Send data
  .read(size) - Receive data
  .close() - Close connection
  Context manager support: with d.dial(...) as conn

Listener (Server)

Listener(driver, port) - Accept connections
  .accept() - Wait for incoming connection
  .close() - Stop listening

CLI Tools (Entry Points)

All available after pip install:

• pilotctl - Main CLI (info, peers, dial, etc)
• pilot-daemon - Background network daemon
• pilot-gateway - HTTP/WebSocket gateway

Bundled Components

Each wheel includes:

• Python SDK (pilotprotocol package)
• Go binaries (daemon, gateway, pilotctl)
• CGO shared library (libpilot.so)
• Entry point scripts
• ~7-8MB total per platform

Platform Support

• Linux: x86_64 (manylinux_2_35+)
• macOS: Intel + Apple Silicon (universal2)
• Windows: Coming soon

Auto-Discovery

SDK finds libpilot library from:

1. ~/.pilot/bin/ (pip install location)
2. Package directory (site-packages/pilotprotocol/bin/)
3. PILOT_LIB_PATH environment variable
4. Development layout (<project>/bin/)

State Management

• Config: ~/.pilot/config.json
• Identity: ~/.pilot/identity.key
• Logs: ~/.pilot/logs/
• Socket: /tmp/pilot.sock (Unix) or named pipe (Windows)

Installation

pip install pilotprotocol

Auto-configures on first run.

Quick Example

from pilotprotocol import Driver

with Driver() as d:
    info = d.info()
    print(f"Address: {info['address']}")
    
    d.set_hostname("my-agent")
    
    peer = d.resolve_hostname("other-agent")
    
    with d.dial(f"{peer['address']}:1000") as conn:
        conn.write(b"Hello!")
        response = conn.read(4096)

Testing

• 34 integration tests covering all core functionality
• Tests run against real daemon in Docker
• 100% coverage of public API

Package Structure

pilotprotocol/
├── __init__.py        # Public API exports
├── client.py          # Driver, Conn, Listener classes
├── cli.py             # Entry point wrappers
├── bin/               # Bundled binaries
│   ├── libpilot.so    # CGO shared library
│   ├── pilot-daemon   # Network daemon
│   ├── pilot-gateway  # HTTP gateway
│   └── pilotctl       # CLI tool
└── py.typed           # Type checking marker

Key Design Decisions

1. No protocol reimplementation - All logic in Go
2. Bundled binaries - Zero external dependencies
3. Entry points over install hooks - Modern packaging
4. State in home directory - Clean package directory
5. Context managers - Pythonic resource management
6. Type hints - Full type coverage with py.typed

[Copilot]

Pull request overview

This PR introduces a Python SDK for the Pilot Protocol, built as a ctypes/FFI wrapper over a CGO-compiled shared library (libpilot.so). This allows Python callers to use the full Go driver without reimplementing the protocol.

Changes:

• New Python SDK (sdk/python/, sdk/cgo/): Package pilotprotocol with Driver, Conn, Listener, and PilotError; CGO bindings in sdk/cgo/bindings.go; CLI entry-point wrappers; build/publish scripts.
• Integration tests (tests/integration/): Docker-based integration test suite testing the CLI (21 tests) and Python SDK (34 tests) against a live agent-alpha agent.
• Documentation & website updates: New Python SDK doc page link added to all sidebar navs, landing page tabs for Shell/Python/ClawHub installation, updated README.md, CONTRIBUTING.md, and registry persistence improvements.

Reviewed changes

Copilot reviewed 70 out of 83 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
sdk/cgo/bindings.go	CGO C-shared library exposing Go driver to Python via uint64 handles
sdk/python/pilotprotocol/__init__.py	Public API exports
sdk/python/pilotprotocol/cli.py	Entry-point wrappers for bundled Go binaries
sdk/python/pyproject.toml	Package metadata and build config
sdk/python/scripts/generate-coverage-badge.sh	Coverage badge generator (has hardcoded local path bug)
tests/integration/Dockerfile	Multi-stage Docker build for integration tests (references nonexistent Go 1.25)
tests/integration/Makefile	Test runner (missing exit 1 on Docker failure)
tests/integration/test_cli.sh	CLI integration tests
pkg/registry/dashboard.go	Snapshot endpoint with spoofable localhost check
pkg/registry/server.go	Dashboard stat persistence; TriggerSnapshot with misleading error return
web/index.html	Landing page with incorrect Python SDK code examples
sdk/python/README.md	Duplicate Development section and inconsistent test counts
web/docs/*.html	Sidebar nav updates to add Python SDK link
examples/python_sdk/	Python example scripts
examples/go/	New Go example programs
.github/workflows/tests.yml	CI workflow for unit + integration tests

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.