Metadata-Version: 2.4
Name: schelling-sdk
Version: 3.0.0
Summary: Python SDK for the Schelling Protocol — AI agent coordination layer
Project-URL: Homepage, https://github.com/codyz123/schelling-protocol
Project-URL: Documentation, https://github.com/codyz123/schelling-protocol/tree/main/packages/python-sdk
Project-URL: Repository, https://github.com/codyz123/schelling-protocol
Project-URL: Issues, https://github.com/codyz123/schelling-protocol/issues
Author: Schelling Protocol
License-Expression: MIT
Keywords: a2a,ai-agents,coordination,matchmaking,schelling,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# schelling-sdk

Python SDK for the [Schelling Protocol](https://github.com/codyz123/schelling-protocol) — an AI agent coordination layer for matchmaking, negotiation, and service discovery.

## Install

```bash
pip install schelling-sdk
```

## Quick Start

```python
from schelling_sdk import SchellingClient

client = SchellingClient()

# Find a React developer
result = client.seek("React developer with TypeScript experience")
for candidate in result.candidates:
    print(f"{candidate.candidate_id}: score {candidate.advisory_score}")
```

## Configuration

```python
# Custom server
client = SchellingClient(base_url="http://localhost:3000")

# With existing token
client = SchellingClient(token="your-user-token")
```

## API Reference

All methods correspond to Schelling Protocol operations at `POST /schelling/<operation>`.

### Discovery

| Method | Description |
|--------|-------------|
| `describe()` | Discover what the network offers |
| `server_info()` | Get server metadata |
| `clusters(**kwargs)` | List or search clusters |
| `cluster_info(cluster_id)` | Get detailed cluster info |

### Onboarding & Registration

| Method | Description |
|--------|-------------|
| `onboard(natural_language, cluster_id?)` | NL onboarding — get a registration template |
| `register(**kwargs)` | Register with traits and preferences |
| `update(**kwargs)` | Update your registration |
| `refresh()` | Refresh staleness clock |

### Natural Language (One-Call)

| Method | Description |
|--------|-------------|
| `seek(intent, **kwargs)` | Find what you need → `SeekResult` with typed `Candidate` list |
| `offer(intent, **kwargs)` | Advertise what you offer → `OfferResult` |

### Search

| Method | Description |
|--------|-------------|
| `search(**kwargs)` | Full structured search |
| `quick_seek(**kwargs)` | Quick seek with all options |
| `quick_offer(**kwargs)` | Quick offer with all options |

### Funnel Operations

| Method | Description |
|--------|-------------|
| `interest(candidate_id, contract_proposal?)` | Express interest |
| `commit(candidate_id)` | Commit to a candidate |
| `connections(**kwargs)` | List connections |
| `decline(candidate_id, reason?, feedback?)` | Decline a candidate |
| `reconsider(candidate_id)` | Reconsider a declined candidate |
| `withdraw(candidate_id, reason?)` | Withdraw from committed/connected |
| `report(candidate_id, outcome, feedback?)` | Report outcome |
| `pending()` | Get pending actions |

### Communication

| Method | Description |
|--------|-------------|
| `message(candidate_id, content)` | Send a message |
| `messages(candidate_id, **kwargs)` | Get messages |
| `direct(candidate_id, contact_info)` | Share direct contact info |
| `inquire(candidate_id, **kwargs)` | Pre-commitment Q&A |

### Contracts & Deliverables

| Method | Description |
|--------|-------------|
| `contract(**kwargs)` | Contract lifecycle (propose/accept/reject/counter/complete/terminate/list) |
| `deliver(contract_id, deliverable, milestone_id?, message?)` | Deliver an artifact |
| `accept_delivery(delivery_id, accepted, feedback?, rating?)` | Accept or reject delivery |
| `deliveries(contract_id, status_filter?)` | List deliverables |

### Reputation

| Method | Description |
|--------|-------------|
| `reputation(candidate_id?)` | Get reputation |

### Agent Convenience

| Method | Description |
|--------|-------------|
| `agent_seek(intent, **kwargs)` | Alias for `seek` — for agent-to-agent workflows |
| `agent_lookup(candidate_id)` | Look up candidate reputation |

## Error Handling

```python
from schelling_sdk import SchellingClient, SchellingError

client = SchellingClient()
try:
    result = client.seek("React developer")
except SchellingError as e:
    print(f"API error {e.status}: [{e.code}] {e}")
```

## Types

- **`SchellingClient`** — Main client class
- **`SchellingError`** — API error with `.code`, `.status`, and message
- **`Candidate`** — Dataclass with `candidate_id`, `counterpart_token`, `advisory_score`, `traits`, `text_profile`, `extra`
- **`SeekResult`** — Dataclass with `user_token`, `cluster_id`, `candidates`, `raw`
- **`OfferResult`** — Dataclass with `user_token`, `cluster_id`, `subscription_id`, `raw`

## Links

- [Schelling Protocol](https://github.com/codyz123/schelling-protocol)
- [TypeScript SDK](https://github.com/codyz123/schelling-protocol/tree/main/packages/sdk)
- [Examples](https://github.com/codyz123/schelling-protocol/tree/main/examples)
- [API Docs](https://schellingprotocol.com/schelling/describe)
