agentdraft 0.1.0__py3-none-any.whl

agentdraft/__init__.py

@@ -0,0 +1,42 @@
+"""AgentDraft — Python SDK.
+
+The scheduling source of truth for AI agents. See https://agentdraft.io/docs.
+
+Quickstart::
+
+    from agentdraft import Client, Conflict
+    from datetime import datetime, timedelta, timezone
+
+    client = Client(api_key="avs_live_...")
+
+    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})")
+"""
+
+from .client import Client
+from .errors import AgentDraftError, AuthError, Conflict, RateLimited, RuleViolation
+from .models import Booking, Hold, Slot
+
+__all__ = [
+    "Client",
+    "AgentDraftError",
+    "AuthError",
+    "Conflict",
+    "RateLimited",
+    "RuleViolation",
+    "Booking",
+    "Hold",
+    "Slot",
+]
+
+__version__ = "0.1.0"

agentdraft/client.py

@@ -0,0 +1,312 @@
+"""The Client class — the SDK's only entrypoint."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from typing import Any, Optional
+
+import httpx
+
+from .errors import AgentDraftError, AuthError, Conflict, RateLimited, RuleViolation
+from .models import AgentIdentity, Booking, Slot
+
+DEFAULT_BASE_URL = "https://api.agentdraft.io"
+
+
+class Client:
+    """Top-level SDK client.
+
+    Parameters
+    ----------
+    api_key:
+        An ``avs_live_…`` key issued from your AgentDraft dashboard. If omitted,
+        reads ``AGENTDRAFT_API_KEY`` from the environment.
+    base_url:
+        Override the API base. Defaults to ``https://api.agentdraft.io``; for
+        local development point at ``http://localhost:8080``.
+    timeout:
+        Per-request timeout in seconds (default 10).
+    user_agent:
+        Override the User-Agent string sent on every request.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 10.0,
+        user_agent: str = "agentdraft-python/0.1.0",
+    ):
+        api_key = api_key or os.environ.get("AGENTDRAFT_API_KEY")
+        if not api_key:
+            raise ValueError("api_key is required (pass it or set AGENTDRAFT_API_KEY)")
+        if not api_key.startswith("avs_live_"):
+            raise ValueError("api_key must start with 'avs_live_'")
+        self._api_key = api_key
+        self._base = (base_url or os.environ.get("AGENTDRAFT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._http = httpx.Client(
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": user_agent},
+        )
+
+        self.availability = _Availability(self)
+        self.bookings = _Bookings(self)
+        self.agents = _Agents(self)
+        self.mailbox = _Mailbox(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        self.close()
+
+    # -- low-level ---------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict | None = None,
+        headers: dict | None = None,
+    ) -> tuple[int, dict, dict]:
+        resp = self._http.request(method, f"{self._base}{path}", json=json, params=params, headers=headers)
+        try:
+            body = resp.json() if resp.content else {}
+        except Exception:
+            body = {"raw": resp.text}
+
+        if resp.status_code >= 400:
+            self._raise_for(resp.status_code, body, resp.headers)
+
+        return resp.status_code, body, dict(resp.headers)
+
+    def _raise_for(self, status: int, body: dict, headers: dict) -> None:
+        if status == 401 or status == 403:
+            raise AuthError(body.get("detail") or str(body), status=status, body=body)
+        if status == 409:
+            raise Conflict(
+                body.get("error", "outranked"),
+                body=body,
+                winning_booking_id=body.get("winning_booking_id"),
+                winning_agent_id=body.get("winning_agent_id"),
+                winning_agent_priority=body.get("winning_agent_priority"),
+                your_priority=body.get("your_priority"),
+                reason=body.get("error", "outranked"),
+            )
+        if status == 422:
+            raise RuleViolation(body.get("detail") or "rule violation", status=status, body=body)
+        if status == 429:
+            retry = headers.get("retry-after") or headers.get("Retry-After")
+            raise RateLimited(
+                "rate limited",
+                body=body,
+                retry_after=int(retry) if retry else None,
+            )
+        raise AgentDraftError(f"HTTP {status}: {body}", status=status, body=body)
+
+
+# -- resources -----------------------------------------------------------------
+
+
+class _Resource:
+    def __init__(self, client: Client):
+        self._c = client
+
+
+class _Availability(_Resource):
+    def list(
+        self,
+        *,
+        start: datetime,
+        end: datetime,
+        duration_minutes: int = 30,
+        granularity_minutes: int = 15,
+        include_holds: bool = True,
+        user_id: Optional[str] = None,
+    ) -> list[Slot]:
+        params: dict[str, Any] = {
+            "range_start": start.isoformat(),
+            "range_end": end.isoformat(),
+            "duration_minutes": duration_minutes,
+            "granularity_minutes": granularity_minutes,
+            "include_holds": str(include_holds).lower(),
+        }
+        if user_id:
+            params["user_id"] = user_id
+        else:
+            # The endpoint requires user_id today; resolve it via /v1/agents/me
+            me = self._c.agents.me()
+            params["user_id"] = me.user_id
+
+        _, body, _ = self._c._request("GET", "/v1/availability", params=params)
+        return [Slot.from_json(s) for s in body.get("slots", [])]
+
+
+class _Bookings(_Resource):
+    def commit(
+        self,
+        *,
+        start: datetime,
+        end: datetime,
+        idempotency_key: Optional[str] = None,
+        buffer_before_min: int = 0,
+        buffer_after_min: int = 0,
+        bump_window_seconds: Optional[int] = None,
+        metadata: Optional[dict] = None,
+    ) -> Booking:
+        return self._post(
+            start=start,
+            end=end,
+            mode="commit",
+            idempotency_key=idempotency_key,
+            buffer_before_min=buffer_before_min,
+            buffer_after_min=buffer_after_min,
+            bump_window_seconds=bump_window_seconds,
+            metadata=metadata,
+        )
+
+    def hold(
+        self,
+        *,
+        start: datetime,
+        end: datetime,
+        idempotency_key: Optional[str] = None,
+        buffer_before_min: int = 0,
+        buffer_after_min: int = 0,
+        metadata: Optional[dict] = None,
+    ) -> Booking:
+        return self._post(
+            start=start,
+            end=end,
+            mode="hold",
+            idempotency_key=idempotency_key,
+            buffer_before_min=buffer_before_min,
+            buffer_after_min=buffer_after_min,
+            metadata=metadata,
+        )
+
+    def release(self, hold_id: str) -> None:
+        self._c._request("POST", f"/v1/holds/{hold_id}/release")
+
+    def cancel(self, booking_id: str) -> None:
+        """Cancel a previously-committed booking owned by this agent."""
+        self._c._request("DELETE", f"/v1/bookings/{booking_id}")
+
+    def _post(self, **kwargs: Any) -> Booking:
+        idempotency_key = kwargs.pop("idempotency_key", None)
+        body = {
+            "start": kwargs["start"].isoformat(),
+            "end": kwargs["end"].isoformat(),
+            "mode": kwargs["mode"],
+            "buffer_before_min": kwargs.get("buffer_before_min", 0),
+            "buffer_after_min": kwargs.get("buffer_after_min", 0),
+        }
+        if kwargs.get("bump_window_seconds") is not None:
+            body["bump_window_seconds"] = kwargs["bump_window_seconds"]
+        if kwargs.get("metadata"):
+            body["metadata"] = kwargs["metadata"]
+
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        _, j, _ = self._c._request("POST", "/v1/bookings", json=body, headers=headers)
+        return Booking.from_json(j)
+
+
+class _Agents(_Resource):
+    def me(self) -> AgentIdentity:
+        _, j, _ = self._c._request("GET", "/v1/agents/me")
+        return AgentIdentity.from_json(j)
+
+
+class _Mailbox(_Resource):
+    """Inbound + outbound mail for the calling agent.
+
+    Threading + recipient on ``reply`` are derived server-side from the
+    original message — the SDK only needs the body. The address returned
+    by ``info()`` is the agent's inbox, suitable for surfacing to humans.
+    """
+
+    def info(self) -> dict:
+        _, j, _ = self._c._request("GET", "/v1/mailbox/me")
+        return j
+
+    def quota(self) -> dict:
+        """Convenience: just the quota sub-object of ``info()``."""
+        return self.info().get("quota", {})
+
+    def list_messages(
+        self,
+        *,
+        limit: int = 25,
+        cursor: Optional[str] = None,
+        direction: Optional[str] = None,
+        booking_id: Optional[str] = None,
+        since: Optional[datetime] = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        if direction:
+            params["direction"] = direction
+        if booking_id:
+            params["booking_id"] = booking_id
+        if since:
+            params["since"] = since.isoformat()
+        _, j, _ = self._c._request("GET", "/v1/mailbox/messages", params=params)
+        return j
+
+    def get_message(self, message_id: str) -> dict:
+        _, j, _ = self._c._request("GET", f"/v1/mailbox/messages/{message_id}")
+        return j
+
+    def send(
+        self,
+        *,
+        to: str,
+        subject: str,
+        body_text: str,
+        booking_id: Optional[str] = None,
+        in_reply_to: Optional[str] = None,
+        reply_to: Optional[str] = None,
+    ) -> dict:
+        body: dict[str, Any] = {"to": to, "subject": subject, "body_text": body_text}
+        if booking_id is not None:
+            body["booking_id"] = booking_id
+        if in_reply_to is not None:
+            body["in_reply_to"] = in_reply_to
+        if reply_to is not None:
+            body["reply_to"] = reply_to
+        _, j, _ = self._c._request("POST", "/v1/mailbox/send", json=body)
+        return j
+
+    def reply(
+        self,
+        message_id: str,
+        *,
+        body_text: str,
+        subject: Optional[str] = None,
+        reply_to: Optional[str] = None,
+    ) -> dict:
+        body: dict[str, Any] = {"body_text": body_text}
+        if subject is not None:
+            body["subject"] = subject
+        if reply_to is not None:
+            body["reply_to"] = reply_to
+        _, j, _ = self._c._request(
+            "POST", f"/v1/mailbox/messages/{message_id}/reply", json=body
+        )
+        return j
+
+    def check_suppression(self, address: str) -> dict:
+        from urllib.parse import quote
+
+        _, j, _ = self._c._request(
+            "GET", f"/v1/mailbox/suppressions/{quote(address, safe='@+.')}"
+        )
+        return j

agentdraft/errors.py

@@ -0,0 +1,58 @@
+"""SDK exception hierarchy.
+
+All AgentDraft errors inherit from ``AgentDraftError``. ``Conflict`` is the
+domain-meaningful one — your booking lost to a higher-priority agent — and
+carries the winner's identity for graceful fallback.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class AgentDraftError(Exception):
+    """Base for all SDK errors."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: dict | None = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body or {}
+
+
+class AuthError(AgentDraftError):
+    """401 / 403 — your API key is missing, invalid, or lacks the required scope."""
+
+
+class Conflict(AgentDraftError):
+    """409 — your booking lost. Inspect ``winning_*`` to decide what to do next."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 409,
+        body: dict,
+        winning_booking_id: Optional[str] = None,
+        winning_agent_id: Optional[str] = None,
+        winning_agent_priority: Optional[int] = None,
+        your_priority: Optional[int] = None,
+        reason: str = "outranked",
+    ):
+        super().__init__(message, status=status, body=body)
+        self.winning_booking_id = winning_booking_id
+        self.winning_agent_id = winning_agent_id
+        self.winning_agent_priority = winning_agent_priority
+        self.your_priority = your_priority
+        self.reason = reason
+
+
+class RuleViolation(AgentDraftError):
+    """422 — the proposed booking violates a rule (working hours, focus block, etc.)."""
+
+
+class RateLimited(AgentDraftError):
+    """429 — you've exceeded your rate limit. ``retry_after`` is in seconds."""
+
+    def __init__(self, message: str, *, status: int = 429, body: dict, retry_after: int | None = None):
+        super().__init__(message, status=status, body=body)
+        self.retry_after = retry_after

agentdraft/models.py

@@ -0,0 +1,64 @@
+"""Lightweight value objects. No Pydantic dep — keep the SDK small."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+
+def _parse_dt(s: Optional[str]) -> Optional[datetime]:
+    if not s:
+        return None
+    return datetime.fromisoformat(s.replace("Z", "+00:00"))
+
+
+@dataclass
+class Booking:
+    booking_id: str
+    status: str  # "COMMITTED" | "HOLD"
+    expires_at: Optional[datetime] = None
+    audit_event_id: Optional[str] = None
+
+    @classmethod
+    def from_json(cls, j: dict) -> "Booking":
+        return cls(
+            booking_id=j["booking_id"],
+            status=j["status"],
+            expires_at=_parse_dt(j.get("expires_at")),
+            audit_event_id=j.get("audit_event_id"),
+        )
+
+
+@dataclass
+class Hold(Booking):
+    """A Booking with status=HOLD. Same shape; semantic alias for clarity."""
+
+    pass
+
+
+@dataclass
+class Slot:
+    start: datetime
+    end: datetime
+
+    @classmethod
+    def from_json(cls, j: dict) -> "Slot":
+        return cls(start=_parse_dt(j["start"]), end=_parse_dt(j["end"]))
+
+
+@dataclass
+class AgentIdentity:
+    agent_id: str
+    user_id: str
+    priority: int
+    scopes: list[str]
+
+    @classmethod
+    def from_json(cls, j: dict) -> "AgentIdentity":
+        return cls(
+            agent_id=j["agent_id"],
+            user_id=j["user_id"],
+            priority=j["priority"],
+            scopes=j.get("scopes", []),
+        )

agentdraft-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+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).

agentdraft-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentdraft/__init__.py,sha256=QxWb3NorY8l9eFT9NhoTBM8ltTmId1CSNjLcCGUfBzs,1058
+agentdraft/client.py,sha256=vbXYcFjKPdLV-QoZ9V_8H1pzTf2kPATJeTPWugtMv08,10305
+agentdraft/errors.py,sha256=qq5S4-BfQ83Jugv8o81Q4BLhOKamDMJjxiuXa7QHDLo,1912
+agentdraft/models.py,sha256=BalmulhbZymr4yRKkG57RSIEFeHmts9lIje-8EbmvW0,1471
+agentdraft/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentdraft-0.1.0.dist-info/licenses/LICENSE,sha256=M1YQ3J9kW25EJEAYueRGXCMrj8wR-quyUrZzRomQXwg,1073
+agentdraft-0.1.0.dist-info/METADATA,sha256=Biu0WBPbuCsW7na2ODV3uZ4Fm9bN9rzvXbkMvh7caB8,5134
+agentdraft-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentdraft-0.1.0.dist-info/top_level.txt,sha256=T5v__C9StkgOlkNaj_iQZs_KXGj8yu2k5N3UDuLBUY4,11
+agentdraft-0.1.0.dist-info/RECORD,,

agentdraft-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentdraft-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentDraft Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentdraft-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentdraft