Metadata-Version: 2.4
Name: pilotprotocol
Version: 1.13.4
Summary: Python SDK for Pilot Protocol - the network stack for AI agents
Author-email: Alexandru Godoroja <alex@pilotprotocol.network>
Maintainer-email: Alexandru Godoroja <alex@pilotprotocol.network>, Teodor Calin <teodor@pilotprotocol.network>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://pilotprotocol.network
Project-URL: Documentation, https://pilotprotocol.network/docs/
Project-URL: Repository, https://github.com/pilot-protocol/pilotprotocol
Project-URL: Bug Tracker, https://github.com/pilot-protocol/pilotprotocol/issues
Project-URL: Changelog, https://github.com/pilot-protocol/pilotprotocol/blob/main/sdk/python/CHANGELOG.md
Keywords: pilot-protocol,networking,p2p,agent,ai,protocol,ctypes,udp,encryption
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: Internet
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.0; extra == "dev"
Dynamic: license-file

# Pilot Protocol — Python SDK

[![ci](https://github.com/pilot-protocol/sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/pilot-protocol/sdk-python/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/pilot-protocol/sdk-python/branch/main/graph/badge.svg)](https://codecov.io/gh/pilot-protocol/sdk-python)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

[![PyPI version](https://img.shields.io/pypi/v/pilotprotocol)](https://pypi.org/project/pilotprotocol/)
[![Python versions](https://img.shields.io/pypi/pyversions/pilotprotocol)](https://pypi.org/project/pilotprotocol/)

Python client for the [Pilot Protocol](https://pilotprotocol.network) overlay network. Gives AI agents and services permanent addresses, encrypted peer-to-peer channels, and a mutual-trust model.

The SDK calls into a pre-built `libpilot` shared library (`.so` / `.dylib` / `.dll`) via `ctypes` and talks to a local `pilot-daemon` over a Unix domain socket.

## Install

```bash
pip install pilotprotocol
```

The wheel ships the native `libpilot` library plus console entry points: `pilotctl`, `pilot-daemon`, `pilot-gateway`, `pilot-updater`.

Supported platforms: Linux (x86_64, arm64), macOS (Intel, Apple Silicon). Windows is experimental.

## Quick start

Make sure a daemon is running:

```bash
pilotctl daemon start --hostname my-agent
```

Then, from your code:

```python
from pilotprotocol import Driver, PilotError

try:
    with Driver() as d:
        info = d.info()
        print(f"address={info['address']}")

        d.set_hostname("my-python-agent")

        peer = d.resolve_hostname("other-agent")
        with d.dial(f"{peer['address']}:1000") as conn:
            conn.write(b"hello")
            print(conn.read(4096))
except (PilotError, FileNotFoundError) as e:
    # Raised when libpilot isn't installed or no daemon is running.
    # Start one with: pilotctl daemon start --hostname my-agent
    print(f"pilot daemon unavailable: {e}")
```

## API overview

`Driver` is the connection to the local daemon. Highlights:

- Identity: `info`, `set_hostname`, `set_visibility`, `set_tags`, `resolve_hostname`
- Trust: `handshake`, `pending_handshakes`, `approve_handshake`, `reject_handshake`, `trusted_peers`, `revoke_trust`
- Streams: `dial`, `listen` (returning `Conn` / `Listener`, both context managers)
- Datagrams: `send_to`, `recv_from`
- Built-in services: `send_message`, `send_file` (data exchange); `publish_event`, `subscribe_event` (event stream); `submit_task` (task queue)
- Config: `set_webhook`, `set_task_exec`, `deregister`, `disconnect`

All daemon-side errors are raised as `PilotError`.

```python
from pilotprotocol import Driver, PilotError

try:
    with Driver() as d:
        d.resolve_hostname("unknown")
except (PilotError, FileNotFoundError) as e:
    print(f"error: {e}")
```

## Native library lookup

The SDK searches for `libpilot.{so,dylib,dll}` in this order:

1. `PILOT_LIB_PATH` environment variable (explicit path)
2. The installed package directory (bundled wheel layout)
3. `~/.pilot/bin/` (entry-point install location)
4. `<project_root>/bin/` (development layout)
5. System library search path

## Examples

See `examples/` for runnable programs:

- `basic_usage.py` — connection, identity, trust
- `data_exchange_demo.py` — messages, files, JSON
- `event_stream_demo.py` — pub/sub
- `task_submit_demo.py` — task delegation
- `pydantic_ai_agent.py` / `pydantic_ai_multiagent.py` — PydanticAI integration

## Testing

```bash
python -m pytest tests/ -v
```

## Links

- Homepage: <https://pilotprotocol.network>
- Issues: <https://github.com/pilot-protocol/sdk-python/issues>
- Node.js SDK: [`pilotprotocol`](https://www.npmjs.com/package/pilotprotocol) on npm
- Swift SDK: [`sdk-swift`](https://github.com/pilot-protocol/sdk-swift)

## License

AGPL-3.0-or-later. See [LICENSE](LICENSE).
