Metadata-Version: 2.4
Name: mesh-protocol
Version: 0.1.0
Summary: Python client for the Capability Mesh Protocol — publish and discover capabilities on a decentralized mesh network.
Project-URL: Homepage, https://github.com/mellowmarshall/mars-protocol
Project-URL: Repository, https://github.com/mellowmarshall/mars-protocol
Project-URL: Issues, https://github.com/mellowmarshall/mars-protocol/issues
Author-email: Marshall Brett <marshall@meshprotocol.dev>
License-Expression: MIT OR Apache-2.0
Keywords: agents,ai,capability-discovery,dht,mesh,p2p
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: System :: Networking
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# mars-protocol

Python client for the [Mesh Agent Routing Standard](https://github.com/mellowmarshall/mars-protocol). A thin wrapper around the mesh-gateway HTTP API that lets you publish and discover capabilities on the decentralized mesh network.

## Install

```bash
pip install mesh-protocol
```

## Live Network

The MARS mesh is live. Start a gateway connected to any hub, then use this SDK:

```bash
# Start the gateway (connects to mesh via QUIC, exposes HTTP)
./target/release/mesh-gateway --seed 5.161.53.251:4433 --listen 0.0.0.0:3000
```

Available hubs:

| Hub | Address | Location |
|-----|---------|----------|
| **us-east** | `5.161.53.251:4433` | Ashburn, VA |
| **us-west** | `5.78.197.92:4433` | Hillsboro, OR |
| **eu-central** | `46.225.55.16:4433` | Nuremberg, DE |
| **ap-southeast** | `5.223.69.128:4433` | Singapore |

## Quick start

```python
from mesh_protocol import MeshClient

with MeshClient("http://localhost:3000") as client:
    # Publish a capability
    result = client.publish(
        "compute/inference/text-generation",
        endpoint="https://my-agent.example.com/v1/generate",
        params={"model": "llama-3.3-70b"},
    )
    print(result.descriptor_id)

    # Discover capabilities
    providers = client.discover("compute/inference")
    for p in providers:
        print(f"{p.type} -> {p.endpoint}")
```

## Async

```python
import asyncio
from mesh_protocol import AsyncMeshClient

async def main():
    async with AsyncMeshClient("http://localhost:3000") as client:
        await client.publish(
            "storage/blob",
            endpoint="https://my-storage.example.com/v1/upload",
        )
        providers = await client.discover("storage")
        print(providers)

asyncio.run(main())
```

## API

| Method | Description |
|--------|-------------|
| `publish(type, endpoint, params=None)` | Publish a capability descriptor |
| `discover(type)` | Discover descriptors matching a type prefix |
| `health()` | Check gateway health |
| `close()` | Close the HTTP connection |

Both `MeshClient` and `AsyncMeshClient` support the context manager protocol (`with` / `async with`).

Errors from the gateway are raised as `MeshError`, which includes the HTTP `status_code` and error `message`.

## License

MIT OR Apache-2.0

## Links

- [MARS Protocol repository](https://github.com/mellowmarshall/mars-protocol)
- [Protocol specification](https://github.com/mellowmarshall/mars-protocol/blob/main/PROTOCOL.md)
