Metadata-Version: 2.4
Name: agentdraft
Version: 0.1.1
Summary: Coordination layer for AI scheduling agents — race-free multi-agent booking with priority ranking and an audit log.
Author-email: AgentDraft Labs <hello@agentdraft.io>
License: MIT
Project-URL: Homepage, https://agentdraft.io
Project-URL: Documentation, https://agentdraft.io/docs
Project-URL: Specification, https://agentdraft.io/spec
Project-URL: Changelog, https://agentdraft.io/changelog
Keywords: agentdraft,ai-agents,agents,calendar,scheduling,booking,coordination,langchain,crewai,autogen,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
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)](https://agentdraft.io/legal/license)

**AgentDraft is the coordination layer for AI scheduling agents.** When two
or more agents — your sales bot, a Cal.com handler, an internal recruiter,
a Claude/OpenAI assistant — write to the same calendar, AgentDraft is the
one API that decides who wins, atomically, with a tamper-evident audit row
for every commit.

This is the official Python SDK. It gives an agent a typed, one-line
surface to participate.

- **Protocol spec:** <https://agentdraft.io/spec>
- **Why it exists:** <https://agentdraft.io/why>
- **Live API reference:** <https://agentdraft.io/docs>

## 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.

## Why a separate API?

Coordinator frameworks (LangChain, LangGraph, CrewAI, AutoGen, Composio,
the OpenAI Agents SDK) coordinate *work between agents* — sequential,
parallel, or graph orchestration of LLM calls and tools. None of them
solve **write contention on the calendar itself**: two agents firing
`POST /events` against Google Calendar at the same moment will both
succeed, and you have a double-booking.

AgentDraft solves only that problem, and solves it once. Every agent
the calendar owner runs calls `bookings.commit(...)` against AgentDraft
before touching the real calendar. The conflict engine uses
time-bucketed conditional writes in DynamoDB inside a single
`TransactWriteItems` — atomic, race-free, no locks. The user ranks
their agents in the dashboard; ties go to the higher-rank agent;
recent commits can be evicted by higher-priority agents inside a
configurable bump window.

## See the race

The repo ships a multi-agent race demo. With the local stack up:

```bash
git clone https://github.com/GipsyChef/agentdraft && cd agentdraft
docker compose up -d dynamodb
pip install -e ".[dev]" -e sdks/python
uvicorn app.main:app --port 8080 &
python scripts/demo_race.py            # 5 agents, ranked priorities, one slot
```

Five agents fire concurrently at the same target slot. The highest-rank
agent wins; the rest get `409 outranked` with the winner's identity for
graceful fallback. The demo prints per-agent latency, the winning
booking id, and a link to the audit trail of the whole race.

## 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_booking_id`,
  `winning_agent_id`, `winning_agent_priority`, `your_priority`, and
  `reason`. The winning booking's `audit_event_id` is available on the
  returned `Booking` model for the agent that *did* win.
- `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.

## Use with LangChain / CrewAI / AutoGen

The SDK is framework-agnostic — wrap any method in a `Tool` and pass it
to your agent. A first-party `agentdraft-langchain` package with ready
`BookingTool` / `AvailabilityTool` / `ConflictAwareBookingTool`
wrappers is on the roadmap.

## Links

- Protocol spec: <https://agentdraft.io/spec>
- API docs: <https://agentdraft.io/docs>
- Changelog: <https://agentdraft.io/changelog>
- Source & issues: <https://github.com/GipsyChef/agentdraft>
- TypeScript SDK: [`@agentdraft/sdk`](https://www.npmjs.com/package/@agentdraft/sdk)

## Security

Found a vulnerability? See <https://agentdraft.io/security> — **do not**
open a public issue for a security report.

## License

MIT — see <https://agentdraft.io/legal/license>.
