relata-sdk 0.2.0__py3-none-any.whl

relata/__init__.py

@@ -0,0 +1,127 @@
+"""
+Relata Python SDK
+=================
+
+Python SDK for the `Relata <https://relata.io>`_ enterprise-grade data
+engine.  Relata is a Rust-native ontology-driven engine for bi-temporal,
+governed knowledge workloads: link analysis, identity resolution, full-text
+and vector search, access-scoped restricted data, and provenance-tracked
+analytics.
+
+Quick start::
+
+    from relata import RelataClient
+
+    with RelataClient("http://localhost:8080", purpose="analytics") as client:
+        # Simple query
+        result = client.query("SELECT * FROM Person WHERE name LIKE 'Ahmed%' LIMIT 10")
+        for row in result:
+            print(row)
+
+        # Fluent query builder
+        result = (
+            client.select("Person")
+            .where("nationality = 'IN'")
+            .as_of("2025-01-01")
+            .with_provenance()
+            .limit(20)
+            .execute()
+        )
+
+Public API
+----------
+- :class:`~relata.client.RelataClient` — main client (sync + async)
+- :class:`~relata.query.QueryBuilder` — fluent SQL builder
+- :mod:`~relata.models` — Pydantic response models
+- :mod:`~relata.exceptions` — SDK exception hierarchy
+"""
+
+from relata.a2a import A2AClient, AsyncA2AClient
+from relata.audit import AsyncAuditClient, AuditClient
+from relata.client import RelataClient
+from relata.exceptions import (
+    AuthError,
+    ConnectionError,
+    PurposeError,
+    QuotaError,
+    RelataError,
+    ServerError,
+)
+from relata.governance import AsyncGovernanceClient, GovernanceClient
+from relata.identity import AsyncIdentityClient, IdentityClient
+from relata.ingest import AsyncIngestClient, IngestClient
+from relata.mcp import AsyncMcpClient, McpClient
+from relata.memory import AsyncMemory, Memory
+from relata.models import (
+    AuditCountResponse,
+    ClusterNode,
+    HealthResponse,
+    IngestDocumentResponse,
+    QueryResult,
+    ReadyReport,
+    Stats,
+    StatusResponse,
+    VersionInfo,
+)
+from relata.objects import AsyncObjectClient, ObjectClient
+from relata.query import QueryBuilder, select
+from relata.s3 import AsyncS3Client, S3Client
+from relata.streaming import AsyncStreamingClient, StreamingClient
+from relata.system import AsyncSystemClient, SystemClient
+from relata.tenants import AsyncTenantAdminClient, TenantAdminClient
+from relata.vectors import AsyncVectorClient, VectorClient
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Client
+    "RelataClient",
+    # High-level memory client
+    "Memory",
+    "AsyncMemory",
+    # v1.1 SDK modules
+    "GovernanceClient",
+    "AsyncGovernanceClient",
+    "McpClient",
+    "AsyncMcpClient",
+    "A2AClient",
+    "AsyncA2AClient",
+    "AuditClient",
+    "AsyncAuditClient",
+    "IdentityClient",
+    "AsyncIdentityClient",
+    "ObjectClient",
+    "AsyncObjectClient",
+    "IngestClient",
+    "AsyncIngestClient",
+    "VectorClient",
+    "AsyncVectorClient",
+    "S3Client",
+    "AsyncS3Client",
+    "SystemClient",
+    "AsyncSystemClient",
+    "StreamingClient",
+    "AsyncStreamingClient",
+    "TenantAdminClient",
+    "AsyncTenantAdminClient",
+    # Query builder
+    "QueryBuilder",
+    "select",
+    # Models
+    "QueryResult",
+    "HealthResponse",
+    "StatusResponse",
+    "AuditCountResponse",
+    "ClusterNode",
+    "IngestDocumentResponse",
+    "VersionInfo",
+    "Stats",
+    "ReadyReport",
+    # Exceptions
+    "RelataError",
+    "PurposeError",
+    "QuotaError",
+    "AuthError",
+    "ConnectionError",
+    "ServerError",
+]

relata/_http.py

@@ -0,0 +1,405 @@
+"""
+Internal HTTP transport layer.
+
+This module is **not** part of the public API.  All internals are subject to
+change without notice.  Callers should use :class:`relata.client.RelataClient`
+instead.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from relata.exceptions import (
+    AuthError,
+    ConflictError,
+    ConnectionError,
+    ForbiddenError,
+    NotFoundError,
+    PurposeError,
+    RateLimitedError,
+    RelataError,
+    ServerError,
+    ValidationError,
+)
+
+# Request / response content-type we always send and expect.
+_CONTENT_TYPE = "application/json"
+
+# Server-side error messages that signal a missing/invalid purpose.
+_PURPOSE_HINTS = frozenset(
+    [
+        "purpose",
+        "purposeregistry",
+        "purpose_registry",
+        "missing purpose",
+        "invalid purpose",
+        "unregistered purpose",
+    ]
+)
+
+# Default retry config (override via RelataClient constructor).
+_DEFAULT_RETRY_ON: frozenset[int] = frozenset({502, 503, 504})
+_DEFAULT_MAX_RETRIES = 0  # off by default — caller must opt in
+_DEFAULT_RETRY_BACKOFF = 0.5
+
+
+def _classify_error(
+    status_code: int,
+    body: dict[str, Any],
+    *,
+    request_id: str | None = None,
+    retry_after: float | None = None,
+) -> RelataError:
+    """Map an HTTP error response to the most-specific SDK exception.
+
+    Parses both the RFC 7807 ``application/problem+json`` shape (``code``,
+    ``type``, ``detail``, ``retryable``, ``request_id``) and the legacy
+    ``{"error": "..."}`` shape.
+    """
+    # RFC 7807 fields — present when the server emits problem+json.
+    code: str | None = body.get("code")
+    type_url: str | None = body.get("type")
+    retryable: bool = bool(body.get("retryable", False))
+    rid = request_id or body.get("request_id")
+    detail: str = (
+        body.get("detail") or body.get("error")
+        or body.get("message") or "unknown server error"
+    )
+    lower_detail = detail.lower()
+
+    # Shared kwargs for every subclass.
+    base_kwargs: dict[str, Any] = {
+        "code": code,
+        "type_url": type_url,
+        "retryable": retryable,
+        "request_id": rid,
+    }
+
+    # Purpose-specific detection — works for both legacy and problem+json.
+    is_purpose = status_code == 400 and (
+        (code and "purpose" in code.lower())
+        or any(hint in lower_detail for hint in _PURPOSE_HINTS)
+    )
+    if is_purpose:
+        return PurposeError(
+            f"Purpose rejected: {detail}. "
+            "Pass purpose= to RelataClient.query() or set a default on the client.",
+            status_code=status_code,
+        )
+
+    if status_code == 401:
+        return AuthError(
+            f"Authentication failed: {detail}. ",
+            status_code=status_code,
+            **base_kwargs,
+        )
+    if status_code == 403:
+        return ForbiddenError(
+            f"Forbidden: {detail}",
+            status_code=status_code,
+            **base_kwargs,
+        )
+    if status_code == 404:
+        return NotFoundError(
+            f"Not found: {detail}",
+            status_code=status_code,
+            **base_kwargs,
+        )
+    if status_code == 409:
+        return ConflictError(
+            f"Conflict: {detail}",
+            status_code=status_code,
+            **base_kwargs,
+        )
+    if status_code == 422:
+        return ValidationError(
+            f"Validation error: {detail}",
+            status_code=status_code,
+            **base_kwargs,
+        )
+    if status_code == 429:
+        return RateLimitedError(
+            f"Rate limited: {detail}",
+            status_code=status_code,
+            retry_after=retry_after,
+            **base_kwargs,
+        )
+    if status_code >= 500:
+        return ServerError(
+            f"Server error: {detail}",
+            status_code=status_code,
+            **base_kwargs,
+        )
+    return RelataError(detail, status_code=status_code, **base_kwargs)
+
+
+def _build_headers(
+    bearer_token: str | None,
+    extra: dict[str, str] | None = None,
+) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "Content-Type": _CONTENT_TYPE,
+        "Accept": _CONTENT_TYPE,
+        "User-Agent": "relata-sdk-python/0.1.0",
+    }
+    if bearer_token:
+        headers["Authorization"] = f"Bearer {bearer_token}"
+    if extra:
+        # Caller-supplied headers win over the SDK defaults so tenants,
+        # acting-as, request-id, etc. can be pinned per-request.
+        headers.update(extra)
+    return headers
+
+
+# ---------------------------------------------------------------------------
+# Sync transport
+# ---------------------------------------------------------------------------
+
+
+class HttpTransport:
+    """Synchronous HTTP transport backed by :mod:`httpx`."""
+
+    def __init__(
+        self,
+        base_url: str,
+        bearer_token: str | None,
+        timeout: float,
+        transport: httpx.BaseTransport | None = None,
+        extra_headers: dict[str, str] | None = None,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        retry_backoff: float = _DEFAULT_RETRY_BACKOFF,
+        retry_on: frozenset[int] = _DEFAULT_RETRY_ON,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=_build_headers(bearer_token, extra_headers),
+            timeout=timeout,
+            transport=transport,
+        )
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+        self._retry_on = retry_on
+
+    def _request_id(self) -> str:
+        return str(uuid.uuid4())
+
+    def _send_with_retry(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_payload: dict[str, Any] | None = None,
+        content: str | bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send an HTTP request with retry + request_id propagation."""
+        # If the caller already set X-Request-ID in the default headers bag,
+        # respect it — only generate a per-attempt UUID when no default exists.
+        has_default_rid = "x-request-id" in {k.lower() for k in self._client.headers}
+        last_exc: RelataError | None = None
+        for attempt in range(self._max_retries + 1):
+            req_headers: dict[str, str] = {}
+            if not has_default_rid:
+                req_headers["X-Request-ID"] = self._request_id()
+            if headers:
+                req_headers.update(headers)
+            try:
+                if method == "GET":
+                    resp = self._client.get(path, headers=req_headers)
+                elif method == "DELETE":
+                    resp = self._client.delete(path, headers=req_headers)
+                elif json_payload is not None:
+                    resp = self._client.request(
+                        method, path, json=json_payload, headers=req_headers
+                    )
+                elif content is not None:
+                    resp = self._client.request(method, path, content=content, headers=req_headers)
+                else:
+                    resp = self._client.request(method, path, headers=req_headers)
+            except httpx.ConnectError as exc:
+                last_exc = ConnectionError(
+                    f"Cannot connect to Relata server: {exc}. "
+                    "Check that the server is running and the base_url is correct."
+                )
+                if attempt < self._max_retries:
+                    time.sleep(self._retry_backoff * (2**attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.TimeoutException as exc:
+                last_exc = ConnectionError(
+                    f"Request timed out: {exc}. "
+                    "Increase timeout= on RelataClient or check server health."
+                )
+                if attempt < self._max_retries:
+                    time.sleep(self._retry_backoff * (2**attempt))
+                    continue
+                raise last_exc from exc
+
+            # Success or non-retryable error — return / raise via _handle.
+            return self._handle(resp)
+
+        # Exhausted retries on a connection error.
+        assert last_exc is not None
+        raise last_exc
+
+    def get(self, path: str) -> dict[str, Any]:
+        """Perform a GET request and return the decoded JSON body."""
+        return self._send_with_retry("GET", path)
+
+    def post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Perform a POST request with a JSON body and return the decoded JSON body."""
+        return self._send_with_retry("POST", path, json_payload=payload)
+
+    def delete(self, path: str) -> dict[str, Any]:
+        """Perform a DELETE request and return the decoded JSON body."""
+        return self._send_with_retry("DELETE", path)
+
+    def patch(self, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Perform a PATCH request with an optional JSON body."""
+        return self._send_with_retry("PATCH", path, json_payload=payload or {})
+
+    def put(self, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Perform a PUT request with an optional JSON body."""
+        return self._send_with_retry("PUT", path, json_payload=payload or {})
+
+    def close(self) -> None:
+        self._client.close()
+
+    @staticmethod
+    def _handle(resp: httpx.Response) -> dict[str, Any]:
+        if resp.is_success:
+            return resp.json()  # type: ignore[no-any-return]
+        try:
+            body: dict[str, Any] = resp.json()
+        except Exception:
+            body = {"error": resp.text or "empty response"}
+        request_id = resp.headers.get("x-request-id")
+        retry_after_hdr = resp.headers.get("retry-after")
+        retry_after = float(retry_after_hdr) if retry_after_hdr else None
+        raise _classify_error(
+            resp.status_code,
+            body,
+            request_id=request_id,
+            retry_after=retry_after,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Async transport
+# ---------------------------------------------------------------------------
+
+
+class AsyncHttpTransport:
+    """Asynchronous HTTP transport backed by :mod:`httpx`."""
+
+    def __init__(
+        self,
+        base_url: str,
+        bearer_token: str | None,
+        timeout: float,
+        transport: httpx.AsyncBaseTransport | None = None,
+        extra_headers: dict[str, str] | None = None,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        retry_backoff: float = _DEFAULT_RETRY_BACKOFF,
+        retry_on: frozenset[int] = _DEFAULT_RETRY_ON,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=_build_headers(bearer_token, extra_headers),
+            timeout=timeout,
+            transport=transport,
+        )
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+        self._retry_on = retry_on
+
+    def _request_id(self) -> str:
+        return str(uuid.uuid4())
+
+    async def _send_with_retry(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_payload: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send an async HTTP request with retry + request_id propagation."""
+        import asyncio
+
+        last_exc: RelataError | None = None
+        for attempt in range(self._max_retries + 1):
+            req_headers = {"X-Request-ID": self._request_id()}
+            try:
+                if method == "GET":
+                    resp = await self._client.get(path, headers=req_headers)
+                elif method == "DELETE":
+                    resp = await self._client.delete(path, headers=req_headers)
+                else:
+                    resp = await self._client.request(
+                        method, path, json=json_payload or {}, headers=req_headers
+                    )
+            except httpx.ConnectError as exc:
+                last_exc = ConnectionError(
+                    f"Cannot connect to Relata server: {exc}."
+                )
+                if attempt < self._max_retries:
+                    await asyncio.sleep(self._retry_backoff * (2**attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.TimeoutException as exc:
+                last_exc = ConnectionError(
+                    f"Request timed out: {exc}."
+                )
+                if attempt < self._max_retries:
+                    await asyncio.sleep(self._retry_backoff * (2**attempt))
+                    continue
+                raise last_exc from exc
+            return self._handle(resp)
+        assert last_exc is not None
+        raise last_exc
+
+    async def get(self, path: str) -> dict[str, Any]:
+        """Perform an async GET request and return the decoded JSON body."""
+        return await self._send_with_retry("GET", path)
+
+    async def post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Perform an async POST request with a JSON body."""
+        return await self._send_with_retry("POST", path, json_payload=payload)
+
+    async def delete(self, path: str) -> dict[str, Any]:
+        """Perform an async DELETE request."""
+        return await self._send_with_retry("DELETE", path)
+
+    async def patch(self, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Perform an async PATCH request with an optional JSON body."""
+        return await self._send_with_retry("PATCH", path, json_payload=payload or {})
+
+    async def put(self, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Perform an async PUT request with an optional JSON body."""
+        return await self._send_with_retry("PUT", path, json_payload=payload or {})
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    @staticmethod
+    def _handle(resp: httpx.Response) -> dict[str, Any]:
+        if resp.is_success:
+            return resp.json()  # type: ignore[no-any-return]
+        try:
+            body: dict[str, Any] = resp.json()
+        except Exception:
+            body = {"error": resp.text or "empty response"}
+        request_id = resp.headers.get("x-request-id")
+        retry_after_hdr = resp.headers.get("retry-after")
+        retry_after = float(retry_after_hdr) if retry_after_hdr else None
+        raise _classify_error(
+            resp.status_code,
+            body,
+            request_id=request_id,
+            retry_after=retry_after,
+        )

relata/a2a.py

@@ -0,0 +1,157 @@
+"""A2A client — Agent-to-Agent task surface (#77 Phase 3).
+
+Wraps ``/a2a/tasks`` (create), ``/a2a/tasks/:id`` (status),
+``/a2a/tasks/:id/stream`` (SSE tail — pairs with the streaming ticket), and
+``/a2a/checkpoints/:thread_id`` (LangGraph checkpointer backing store).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from relata._http import AsyncHttpTransport, HttpTransport
+
+if TYPE_CHECKING:
+    import httpx
+
+    from relata.client import RelataClient
+
+
+class A2AClient:
+    """Synchronous A2A client — submit / poll / list tasks; manage checkpoints."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        bearer_token: str | None = None,
+        timeout: float = 30.0,
+        extra_headers: dict[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._t = HttpTransport(
+            base_url, bearer_token, timeout, transport=transport, extra_headers=extra_headers
+        )
+
+    @classmethod
+    def from_client(cls, client: RelataClient) -> A2AClient:
+        return cls(
+            client._base_url,
+            bearer_token=client._bearer_token,
+            timeout=client._timeout,
+            extra_headers=client._extra_headers,
+        )
+
+    def submit_task(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Submit a long-running A2A task. The ``payload`` matches the A2A
+        protocol — typically ``{"name": "...", "input": {...}, "skill": ...}``.
+        Returns the task record with its ``id`` and initial ``status``."""
+        return self._t.post("/a2a/tasks", payload)
+
+    def get_task(self, task_id: str) -> dict[str, Any]:
+        """Poll a task's status. Returns ``{"id", "status", "result", "error", ...}``."""
+        return self._t.get(f"/a2a/tasks/{task_id}")
+
+    def list_checkpoints(self, thread_id: str) -> list[dict[str, Any]]:
+        """List the LangGraph checkpoints for a thread (used by
+        :class:`relata_langgraph.RelataCheckpointer`)."""
+        data = self._t.get(f"/a2a/checkpoints/{thread_id}")
+        checkpoints = data.get("checkpoints") if isinstance(data, dict) else data
+        return checkpoints if isinstance(checkpoints, list) else []
+
+    def load_checkpoint(self, thread_id: str, checkpoint_id: str) -> dict[str, Any]:
+        """Load a specific checkpoint by id (``GET /a2a/checkpoints/:t/:c``)."""
+        return self._t.get(f"/a2a/checkpoints/{thread_id}/{checkpoint_id}")
+
+    def save_checkpoint(
+        self,
+        thread_id: str,
+        checkpoint_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Save (PUT) a checkpoint. ``payload`` matches the LangGraph
+        checkpointer shape (``{"checkpoint": ..., "metadata": ...}``).
+        Returns the server's save receipt."""
+        return self._t.put(
+            f"/a2a/checkpoints/{thread_id}/{checkpoint_id}",
+            payload,
+        )
+
+    def agent_card(self) -> dict[str, Any]:
+        """Fetch the A2A agent card (``GET /.well-known/agent.json``).
+
+        The card advertises the server's A2A capabilities, skills, and
+        authentication modes to discovery clients."""
+        return self._t.get("/.well-known/agent.json")
+
+    def close(self) -> None:
+        self._t.close()
+
+    def __enter__(self) -> A2AClient:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+
+class AsyncA2AClient:
+    """Asynchronous A2A client — see :class:`A2AClient`."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        bearer_token: str | None = None,
+        timeout: float = 30.0,
+        extra_headers: dict[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._t = AsyncHttpTransport(
+            base_url, bearer_token, timeout, transport=transport, extra_headers=extra_headers
+        )
+
+    @classmethod
+    def from_client(cls, client: RelataClient) -> AsyncA2AClient:
+        return cls(
+            client._base_url,
+            bearer_token=client._bearer_token,
+            timeout=client._timeout,
+            extra_headers=client._extra_headers,
+        )
+
+    async def submit_task(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return await self._t.post("/a2a/tasks", payload)
+
+    async def get_task(self, task_id: str) -> dict[str, Any]:
+        return await self._t.get(f"/a2a/tasks/{task_id}")
+
+    async def list_checkpoints(self, thread_id: str) -> list[dict[str, Any]]:
+        data = await self._t.get(f"/a2a/checkpoints/{thread_id}")
+        checkpoints = data.get("checkpoints") if isinstance(data, dict) else data
+        return checkpoints if isinstance(checkpoints, list) else []
+
+    async def load_checkpoint(self, thread_id: str, checkpoint_id: str) -> dict[str, Any]:
+        return await self._t.get(f"/a2a/checkpoints/{thread_id}/{checkpoint_id}")
+
+    async def save_checkpoint(
+        self,
+        thread_id: str,
+        checkpoint_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return await self._t.put(
+            f"/a2a/checkpoints/{thread_id}/{checkpoint_id}",
+            payload,
+        )
+
+    async def agent_card(self) -> dict[str, Any]:
+        return await self._t.get("/.well-known/agent.json")
+
+    async def close(self) -> None:
+        await self._t.aclose()
+
+    async def __aenter__(self) -> AsyncA2AClient:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()