Status: ready-for-agent

# 10 — `meshnet` Python SDK

## What to build

A Python SDK (`packages/sdk`) that wraps the OpenAI-compatible gateway and exposes network-specific controls that the raw OpenAI SDK cannot express. The SDK is the recommended interface for developers who want more than basic inference.

The SDK surface:

```python
from meshnet import Client

client = Client(api_key="...", base_url="https://api.meshnet.ai")

# Basic inference (identical to OpenAI SDK)
response = client.chat.completions.create(model="llama-3-70b", messages=[...])

# Network-specific features
client.wallet.balance()          # SOL/USDC balance remaining
client.wallet.top_up(amount_sol=1.0)   # returns a Solana payment address + QR
client.models.available()        # list of routable model presets with shard coverage %
client.request(redundancy=2)     # route through 2 independent chains, return majority
client.estimate_cost(model="llama-3-70b", tokens=1000)  # cost in SOL before sending
```

The SDK must not require clients to hold or know about our native token. All wallet operations are in SOL or USDC.

## Acceptance criteria

- [ ] `pip install meshnet` installs the SDK
- [ ] `Client.chat.completions.create(...)` works identically to the OpenAI SDK (same parameters, same response shape)
- [ ] `client.wallet.balance()` returns the current SOL/USDC balance for the API key
- [ ] `client.wallet.top_up()` returns a valid Solana payment address
- [ ] `client.models.available()` returns model presets with shard coverage percentage
- [ ] `client.estimate_cost(model, tokens)` returns a cost estimate in SOL before the request is sent
- [ ] `client.request(redundancy=2)` sends the same prompt to two independent inference routes and returns the majority response
- [ ] The SDK is typed (py.typed, full type stubs)
- [ ] An integration test covers each SDK method against a local gateway + tracker + stub nodes

## Blocked by

- `05-openai-compatible-gateway.md`
- `06-solana-stake-and-settlement.md`