Metadata-Version: 2.4
Name: agentdraft
Version: 0.1.0
Summary: Python SDK for AgentDraft — the scheduling source of truth for AI agents
Author-email: AgentDraft Labs <hello@agentdraft.io>
License: MIT
Project-URL: Homepage, https://agentdraft.io
Project-URL: Documentation, https://agentdraft.io/docs
Project-URL: Repository, https://github.com/GipsyChef/agentdraft
Project-URL: Issues, https://github.com/GipsyChef/agentdraft/issues
Project-URL: Changelog, https://github.com/GipsyChef/agentdraft/blob/main/sdks/python/CHANGELOG.md
Keywords: calendar,scheduling,ai-agents,agentdraft
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# agentdraft — Python SDK

[![PyPI](https://img.shields.io/pypi/v/agentdraft.svg)](https://pypi.org/project/agentdraft/)
[![Python](https://img.shields.io/pypi/pyversions/agentdraft.svg)](https://pypi.org/project/agentdraft/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

The official Python SDK for [AgentDraft](https://agentdraft.io) — the
scheduling source of truth for AI agents.

AgentDraft is the coordination layer that prevents AI scheduling agents
from colliding on the same calendar. Every agent calls one API before
booking; every commit goes through one deterministic engine; every
action is recorded in one tamper-evident audit log.

This SDK gives Python agents a typed, one-line surface to participate.

## Install

```bash
pip install agentdraft
```

Requires Python 3.9+.

## Quickstart

```python
from datetime import datetime, timedelta, timezone
from agentdraft import Client, Conflict

client = Client(api_key="avs_live_...")   # or set AGENTDRAFT_API_KEY

start = datetime.now(timezone.utc) + timedelta(hours=4)
end   = start + timedelta(minutes=30)

try:
    booking = client.bookings.commit(
        start=start, end=end,
        idempotency_key="ik_call_42",
        metadata={"title": "Discovery call"},
    )
    print("booked:", booking.booking_id)
except Conflict as e:
    print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")
```

A losing agent gets a typed `Conflict` exception, not a timeout — it
knows who won, by what priority, and where the audit row lives, so
fallback behavior (propose an alternate, escalate, defer) is a clean
`except` clause away.

## Authentication

API keys are issued from the AgentDraft dashboard and start with
`avs_live_`. Pass it explicitly or let the client read it from the
environment:

```python
Client(api_key="avs_live_...")
# or
import os; os.environ["AGENTDRAFT_API_KEY"] = "avs_live_..."
Client()
```

For local development against a dev backend, point at it via
`AGENTDRAFT_BASE_URL` or the `base_url=` kwarg.

## Surface

| Attribute | Purpose |
|---|---|
| `client.availability` | Read merged availability across all agents writing to the calendar |
| `client.bookings`     | `hold`, `release`, `commit`, `cancel` — the four state transitions |
| `client.agents`       | `me()` — confirm key + current priority + scopes |
| `client.mailbox`      | Inbound/outbound mail surface for agents that book via email |

All blocking I/O. An async client is on the roadmap; for now wrap with
`asyncio.to_thread` if you need concurrency.

## Error types

Every failure is a typed exception so callers can branch precisely:

- `Conflict` — your write was outranked. Carries `winning_agent_id`,
  `winning_agent_priority`, `winning_booking_id`, `audit_event_id`.
- `AuthError` — bad/missing/expired API key.
- `RateLimited` — token bucket exhausted. Has `retry_after_seconds`.
- `RuleViolation` — request was syntactically valid but violated a
  rule (focus block, daily cap, business hours).
- `AgentDraftError` — base class; catch this if you only need a
  catch-all.

## Idempotency

Pass `idempotency_key=` to `bookings.commit(...)`. The server caches the
result by `(agent_id, key)` for 24 hours, so a retry over a flaky network
returns the original booking, not a duplicate.

## Links

- Protocol spec: <https://agentdraft.io/spec>
- API docs: <https://agentdraft.io/docs>
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Issues / source: <https://github.com/GipsyChef/agentdraft>
- TypeScript SDK: [`@agentdraft/sdk`](https://www.npmjs.com/package/@agentdraft/sdk)

## Security

Found a vulnerability? Please follow [SECURITY.md](SECURITY.md) — **do
not** open a public issue for a security report.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). This SDK lives inside the
[`GipsyChef/agentdraft`](https://github.com/GipsyChef/agentdraft)
monorepo under `sdks/python/`.

## License

MIT — see [LICENSE](LICENSE).
