crewlayer 0.1.0__py3-none-any.whl

crewlayer/__init__.py

@@ -0,0 +1,54 @@
+"""CrewLayer SDK — official Python client for the CrewLayer AI agent backend."""
+from crewlayer._client import CrewLayerAsyncClient, CrewLayerClient
+from crewlayer._exceptions import (
+    AuthError,
+    ConflictError,
+    CrewLayerError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+from crewlayer._types import (
+    ActionPage,
+    ActionRecord,
+    ActionStats,
+    ContextEntry,
+    ContextNamespace,
+    ExtractResult,
+    MemoryItem,
+    MemoryPage,
+    Message,
+    RecallResult,
+    ShortMemory,
+    ToolStat,
+)
+
+__all__ = [
+    # Clients
+    "CrewLayerClient",
+    "CrewLayerAsyncClient",
+    # Exceptions
+    "CrewLayerError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    # Types — memory
+    "Message",
+    "ShortMemory",
+    "MemoryItem",
+    "RecallResult",
+    "ExtractResult",
+    "MemoryPage",
+    # Types — actions
+    "ActionRecord",
+    "ActionPage",
+    "ToolStat",
+    "ActionStats",
+    # Types — context
+    "ContextEntry",
+    "ContextNamespace",
+]
+
+__version__ = "0.1.0"

crewlayer/_actions.py

@@ -0,0 +1,153 @@
+"""Actions resource clients — sync and async."""
+from __future__ import annotations
+
+from typing import Any
+
+from crewlayer._http import AsyncTransport, SyncTransport
+from crewlayer._types import ActionPage, ActionRecord, ActionStats
+
+
+class ActionsClient:
+    """Synchronous action log operations."""
+
+    def __init__(self, http: SyncTransport) -> None:
+        self._http = http
+
+    def log(
+        self,
+        agent_id: str,
+        tool_name: str,
+        input_params: dict[str, Any],
+        output_result: dict[str, Any],
+        status: str,
+        *,
+        session_id: str | None = None,
+        duration_ms: int | None = None,
+        error_msg: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ActionRecord:
+        """Record an immutable action entry for the agent."""
+        data = self._http.request(
+            "POST",
+            f"/v1/agents/{agent_id}/actions",
+            json={
+                "tool_name": tool_name,
+                "input_params": input_params,
+                "output_result": output_result,
+                "status": status,
+                "session_id": session_id,
+                "duration_ms": duration_ms,
+                "error_msg": error_msg,
+                "metadata": metadata or {},
+            },
+        )
+        return ActionRecord._from(data)
+
+    def get(self, agent_id: str, action_id: str) -> ActionRecord:
+        """Retrieve a single action by ID."""
+        data = self._http.request("GET", f"/v1/agents/{agent_id}/actions/{action_id}")
+        return ActionRecord._from(data)
+
+    def list(
+        self,
+        agent_id: str,
+        *,
+        tool: str | None = None,
+        status: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> ActionPage:
+        """List actions with optional filters. Paginated via cursor."""
+        params: dict[str, Any] = {"limit": limit}
+        if tool is not None:
+            params["tool"] = tool
+        if status is not None:
+            params["status"] = status
+        if since is not None:
+            params["since"] = since
+        if until is not None:
+            params["until"] = until
+        if cursor is not None:
+            params["cursor"] = cursor
+        data = self._http.request("GET", f"/v1/agents/{agent_id}/actions", params=params)
+        return ActionPage._from(data)
+
+    def stats(self, agent_id: str) -> ActionStats:
+        """Aggregate statistics: totals, error rate, average duration, per-tool breakdown."""
+        data = self._http.request("GET", f"/v1/agents/{agent_id}/actions/stats")
+        return ActionStats._from(data)
+
+
+class AsyncActionsClient:
+    """Asynchronous action log operations."""
+
+    def __init__(self, http: AsyncTransport) -> None:
+        self._http = http
+
+    async def log(
+        self,
+        agent_id: str,
+        tool_name: str,
+        input_params: dict[str, Any],
+        output_result: dict[str, Any],
+        status: str,
+        *,
+        session_id: str | None = None,
+        duration_ms: int | None = None,
+        error_msg: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ActionRecord:
+        """Record an immutable action entry for the agent."""
+        data = await self._http.request(
+            "POST",
+            f"/v1/agents/{agent_id}/actions",
+            json={
+                "tool_name": tool_name,
+                "input_params": input_params,
+                "output_result": output_result,
+                "status": status,
+                "session_id": session_id,
+                "duration_ms": duration_ms,
+                "error_msg": error_msg,
+                "metadata": metadata or {},
+            },
+        )
+        return ActionRecord._from(data)
+
+    async def get(self, agent_id: str, action_id: str) -> ActionRecord:
+        """Retrieve a single action by ID."""
+        data = await self._http.request("GET", f"/v1/agents/{agent_id}/actions/{action_id}")
+        return ActionRecord._from(data)
+
+    async def list(
+        self,
+        agent_id: str,
+        *,
+        tool: str | None = None,
+        status: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        limit: int = 50,
+        cursor: str | None = None,
+    ) -> ActionPage:
+        """List actions with optional filters. Paginated via cursor."""
+        params: dict[str, Any] = {"limit": limit}
+        if tool is not None:
+            params["tool"] = tool
+        if status is not None:
+            params["status"] = status
+        if since is not None:
+            params["since"] = since
+        if until is not None:
+            params["until"] = until
+        if cursor is not None:
+            params["cursor"] = cursor
+        data = await self._http.request("GET", f"/v1/agents/{agent_id}/actions", params=params)
+        return ActionPage._from(data)
+
+    async def stats(self, agent_id: str) -> ActionStats:
+        """Aggregate statistics: totals, error rate, average duration, per-tool breakdown."""
+        data = await self._http.request("GET", f"/v1/agents/{agent_id}/actions/stats")
+        return ActionStats._from(data)

crewlayer/_client.py

@@ -0,0 +1,87 @@
+"""Top-level CrewLayer clients — sync and async."""
+from __future__ import annotations
+
+from typing import Any
+
+from crewlayer._actions import ActionsClient, AsyncActionsClient
+from crewlayer._context import AsyncContextClient, ContextClient
+from crewlayer._http import AsyncTransport, SyncTransport
+from crewlayer._memory import AsyncMemoryClient, MemoryClient
+
+_DEFAULT_BASE_URL = "http://localhost:8000"
+
+
+class CrewLayerClient:
+    """Synchronous CrewLayer client.
+
+    Usage::
+
+        client = CrewLayerClient(api_key="crwl_...")
+        client.memory.append(agent_id="...", role="user", content="Hello")
+        result = client.memory.recall(agent_id="...", query="user preferences")
+        client.close()
+
+    As a context manager::
+
+        with CrewLayerClient(api_key="crwl_...") as client:
+            client.actions.log(agent_id="...", tool_name="send_email", ...)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+    ) -> None:
+        self._http = SyncTransport(api_key, base_url)
+        self.memory = MemoryClient(self._http)
+        self.actions = ActionsClient(self._http)
+        self.context = ContextClient(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> CrewLayerClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class CrewLayerAsyncClient:
+    """Asynchronous CrewLayer client.
+
+    Usage::
+
+        client = CrewLayerAsyncClient(api_key="crwl_...")
+        await client.memory.append(agent_id="...", role="user", content="Hello")
+        result = await client.memory.recall(agent_id="...", query="user preferences")
+        await client.aclose()
+
+    As an async context manager::
+
+        async with CrewLayerAsyncClient(api_key="crwl_...") as client:
+            await client.actions.log(agent_id="...", tool_name="send_email", ...)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+    ) -> None:
+        self._http = AsyncTransport(api_key, base_url)
+        self.memory = AsyncMemoryClient(self._http)
+        self.actions = AsyncActionsClient(self._http)
+        self.context = AsyncContextClient(self._http)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> CrewLayerAsyncClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

crewlayer/_context.py

@@ -0,0 +1,107 @@
+"""Context (blackboard) resource clients — sync and async."""
+from __future__ import annotations
+
+from typing import Any
+
+from crewlayer._http import AsyncTransport, SyncTransport
+from crewlayer._types import ContextEntry, ContextNamespace
+
+
+class ContextClient:
+    """Synchronous shared blackboard operations."""
+
+    def __init__(self, http: SyncTransport) -> None:
+        self._http = http
+
+    def write(
+        self,
+        namespace: str,
+        key: str,
+        value: dict[str, Any],
+        *,
+        written_by: str | None = None,
+        expires_at: str | None = None,
+        expected_version: int | None = None,
+    ) -> ContextEntry:
+        """Write or overwrite a context entry.
+
+        Pass expected_version to enable optimistic locking:
+        - Use 0 to assert the key must not yet exist.
+        - Use the version you last read to prevent clobbering concurrent writes.
+        Raises ConflictError on mismatch.
+        """
+        data = self._http.request(
+            "PUT",
+            f"/v1/context/{namespace}/{key}",
+            json={
+                "value": value,
+                "written_by": written_by,
+                "expires_at": expires_at,
+                "expected_version": expected_version,
+            },
+        )
+        return ContextEntry._from(data)
+
+    def read(self, namespace: str, key: str) -> ContextEntry:
+        """Read a context entry. Raises NotFoundError if absent or expired."""
+        data = self._http.request("GET", f"/v1/context/{namespace}/{key}")
+        return ContextEntry._from(data)
+
+    def list_namespace(self, namespace: str) -> ContextNamespace:
+        """List all non-expired entries in a namespace, ordered by key."""
+        data = self._http.request("GET", f"/v1/context/{namespace}")
+        return ContextNamespace._from(data)
+
+    def delete(self, namespace: str, key: str) -> None:
+        """Delete a context entry. Raises NotFoundError if it does not exist."""
+        self._http.request("DELETE", f"/v1/context/{namespace}/{key}")
+
+
+class AsyncContextClient:
+    """Asynchronous shared blackboard operations."""
+
+    def __init__(self, http: AsyncTransport) -> None:
+        self._http = http
+
+    async def write(
+        self,
+        namespace: str,
+        key: str,
+        value: dict[str, Any],
+        *,
+        written_by: str | None = None,
+        expires_at: str | None = None,
+        expected_version: int | None = None,
+    ) -> ContextEntry:
+        """Write or overwrite a context entry.
+
+        Pass expected_version to enable optimistic locking:
+        - Use 0 to assert the key must not yet exist.
+        - Use the version you last read to prevent clobbering concurrent writes.
+        Raises ConflictError on mismatch.
+        """
+        data = await self._http.request(
+            "PUT",
+            f"/v1/context/{namespace}/{key}",
+            json={
+                "value": value,
+                "written_by": written_by,
+                "expires_at": expires_at,
+                "expected_version": expected_version,
+            },
+        )
+        return ContextEntry._from(data)
+
+    async def read(self, namespace: str, key: str) -> ContextEntry:
+        """Read a context entry. Raises NotFoundError if absent or expired."""
+        data = await self._http.request("GET", f"/v1/context/{namespace}/{key}")
+        return ContextEntry._from(data)
+
+    async def list_namespace(self, namespace: str) -> ContextNamespace:
+        """List all non-expired entries in a namespace, ordered by key."""
+        data = await self._http.request("GET", f"/v1/context/{namespace}")
+        return ContextNamespace._from(data)
+
+    async def delete(self, namespace: str, key: str) -> None:
+        """Delete a context entry. Raises NotFoundError if it does not exist."""
+        await self._http.request("DELETE", f"/v1/context/{namespace}/{key}")

crewlayer/_exceptions.py

@@ -0,0 +1,71 @@
+"""Typed exception hierarchy for the CrewLayer SDK."""
+from __future__ import annotations
+
+from typing import Any
+
+
+class CrewLayerError(Exception):
+    """Base class for all CrewLayer SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self!s}, status_code={self.status_code})"
+
+
+class AuthError(CrewLayerError):
+    """Raised on HTTP 401 / 403 — invalid or missing API key."""
+
+
+class NotFoundError(CrewLayerError):
+    """Raised on HTTP 404 — resource not found."""
+
+
+class ConflictError(CrewLayerError):
+    """Raised on HTTP 409 — optimistic locking version conflict."""
+
+
+class RateLimitError(CrewLayerError):
+    """Raised on HTTP 429 — request rate limit exceeded."""
+
+
+class ServerError(CrewLayerError):
+    """Raised on HTTP 5xx — transient server-side error (after retries exhausted)."""
+
+
+_STATUS_MAP: dict[int, type[CrewLayerError]] = {
+    401: AuthError,
+    403: AuthError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+}
+
+
+def raise_for_response(response: Any) -> None:  # response: httpx.Response
+    """Raise the appropriate SDK exception if the response is not successful."""
+    if response.is_success:
+        return
+    try:
+        body: dict[str, Any] = response.json()
+        detail: str = body.get("detail", response.text)
+    except Exception:
+        body = {}
+        detail = response.text
+
+    status = response.status_code
+    if status >= 500:
+        cls: type[CrewLayerError] = ServerError
+    else:
+        cls = _STATUS_MAP.get(status, CrewLayerError)
+
+    raise cls(detail, status_code=status, response=body)

crewlayer/_http.py

@@ -0,0 +1,101 @@
+"""HTTP transports with automatic retry on transient 5xx errors."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import httpx
+
+from crewlayer._exceptions import raise_for_response
+
+_RETRY_ON = frozenset({500, 502, 503, 504})
+_MAX_RETRIES = 3
+
+
+class SyncTransport:
+    """Synchronous HTTP transport built on httpx.Client."""
+
+    def __init__(self, api_key: str, base_url: str) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key},
+            timeout=30.0,
+        )
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Execute a request, retrying on 5xx with exponential backoff.
+
+        Backoff: 1 s, 2 s, 4 s (2^attempt seconds, up to _MAX_RETRIES retries).
+        Returns {} for 204 No Content responses.
+        """
+        response: httpx.Response | None = None
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if attempt < _MAX_RETRIES:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise
+            if response.status_code in _RETRY_ON and attempt < _MAX_RETRIES:
+                time.sleep(2 ** attempt)
+                continue
+            break
+
+        assert response is not None
+        raise_for_response(response)
+        return {} if response.status_code == 204 else response.json()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> SyncTransport:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class AsyncTransport:
+    """Asynchronous HTTP transport built on httpx.AsyncClient."""
+
+    def __init__(self, api_key: str, base_url: str) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key},
+            timeout=30.0,
+        )
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Execute a request, retrying on 5xx with exponential backoff (async sleep).
+
+        Backoff: 1 s, 2 s, 4 s (2^attempt seconds, up to _MAX_RETRIES retries).
+        Returns {} for 204 No Content responses.
+        """
+        response: httpx.Response | None = None
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if attempt < _MAX_RETRIES:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+                raise
+            if response.status_code in _RETRY_ON and attempt < _MAX_RETRIES:
+                await asyncio.sleep(2 ** attempt)
+                continue
+            break
+
+        assert response is not None
+        raise_for_response(response)
+        return {} if response.status_code == 204 else response.json()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncTransport:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()