vedika-agent-sdk 0.2.0__py3-none-any.whl

vedika_agent/__init__.py

@@ -0,0 +1,65 @@
+"""Public entry point for the Vedika agent SDK."""
+
+from .client import Transport, VedikaAgent, create_agent
+from .errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    StreamError,
+    VedikaAgentError,
+    is_vedika_agent_error,
+)
+from .stream import (
+    Turn,
+    format_last_event_id,
+    parse_chunk,
+    parse_sse_chunk,
+    UI_MESSAGE_STREAM_HEADER,
+)
+from .types import (
+    Artifact,
+    CancelTurnOptions,
+    CreateThreadOptions,
+    Json,
+    MemoryToggles,
+    ResumeTurnOptions,
+    SendTurnOptions,
+    Thread,
+    TurnInput,
+    TurnOutcome,
+    UIMessageStreamChunk,
+)
+
+__all__ = [
+    "VedikaAgent",
+    "create_agent",
+    "Transport",
+    "VedikaAgentError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "ServerError",
+    "StreamError",
+    "ProtocolError",
+    "is_vedika_agent_error",
+    "parse_chunk",
+    "parse_sse_chunk",
+    "format_last_event_id",
+    "UI_MESSAGE_STREAM_HEADER",
+    "Artifact",
+    "CancelTurnOptions",
+    "CreateThreadOptions",
+    "Json",
+    "MemoryToggles",
+    "ResumeTurnOptions",
+    "SendTurnOptions",
+    "Thread",
+    "Turn",
+    "TurnInput",
+    "TurnOutcome",
+    "UIMessageStreamChunk",
+]

vedika_agent/_min_sdk.py

@@ -0,0 +1,138 @@
+"""The "server says your SDK is too old" warning.
+
+Every harness response may carry ``X-Harness-Min-Sdk: <major.minor.patch>``.
+When this SDK's own version is lower, one ``SdkVersionWarning`` is emitted per
+process and the SDK keeps working. The check only ever warns: it never raises,
+never delays a call and never changes retry or error behaviour.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+import threading
+import warnings
+from typing import Any, Mapping, Optional, Tuple
+
+#: Response header (lower-case; header names are case-insensitive).
+MIN_SDK_HEADER = "x-harness-min-sdk"
+
+#: Distribution name from ``pyproject.toml``.
+PACKAGE_NAME = "vedika-agent-sdk"
+
+# Three dot-separated groups of 1 to 9 ASCII digits. Written as [0-9], not \d,
+# because \d also matches non-ASCII digits in Python.
+_VERSION_CORE = re.compile(r"[0-9]{1,9}\.[0-9]{1,9}\.[0-9]{1,9}")
+
+Version = Tuple[int, int, int]
+
+
+class SdkVersionWarning(UserWarning):
+    """This SDK is older than the minimum version the server supports."""
+
+
+def parse_version(value: Any) -> Optional[Version]:
+    """Parse ``major.minor.patch``, ignoring a prerelease or build suffix.
+
+    Returns ``None`` for anything that is not exactly three dot-separated
+    digit groups of at most nine digits each.
+    """
+    if not isinstance(value, str):
+        return None
+    core = re.split(r"[-+]", value.strip(), maxsplit=1)[0]
+    if _VERSION_CORE.fullmatch(core) is None:
+        return None
+    major, minor, patch = core.split(".")
+    return int(major), int(minor), int(patch)
+
+
+def compare_versions(own: Any, minimum: Any) -> Optional[int]:
+    """Compare two versions numerically.
+
+    Returns -1 when ``own`` is lower than ``minimum``, 0 when equal, 1 when
+    higher, and ``None`` when either side cannot be compared.
+    """
+    a = parse_version(own)
+    b = parse_version(minimum)
+    if a is None or b is None:
+        return None
+    return (a > b) - (a < b)
+
+
+def warning_message(package_name: str, own_version: str, min_version: str) -> str:
+    return (
+        f"{package_name} {own_version} is older than the minimum supported version "
+        f"{min_version}. Upgrade to {min_version} or later."
+    )
+
+
+@functools.lru_cache(maxsize=1)
+def _own_version() -> Optional[str]:
+    try:
+        from importlib.metadata import version
+
+        return version(PACKAGE_NAME)
+    except Exception:
+        return None
+
+
+def _header_value(headers: Optional[Mapping[str, Any]]) -> Optional[str]:
+    if not headers:
+        return None
+    value = headers.get(MIN_SDK_HEADER)
+    if value is None:
+        for key, candidate in headers.items():
+            if isinstance(key, str) and key.lower() == MIN_SDK_HEADER:
+                value = candidate
+                break
+    if isinstance(value, bytes):
+        value = value.decode("ascii", errors="replace")
+    return value if isinstance(value, str) else None
+
+
+_lock = threading.Lock()
+_warned = False
+
+
+def _reset_min_sdk_warning_for_tests() -> None:
+    """Test-only: allow the once-per-process warning to fire again."""
+    global _warned
+    with _lock:
+        _warned = False
+
+
+def check_min_sdk_header(
+    headers: Optional[Mapping[str, Any]],
+    *,
+    own_version: Optional[str] = None,
+    stacklevel: int = 4,
+) -> None:
+    """Warn once per process when the server's minimum SDK is above ours.
+
+    ``stacklevel`` counts from this function: 2 is the caller, so the default
+    of 4 points at the code that called ``agent.threads.<method>()``.
+    Swallows every failure, including a warnings filter set to ``error``.
+    """
+    global _warned
+    if _warned:
+        return
+    try:
+        minimum = parse_version(_header_value(headers))
+        if minimum is None:
+            return
+        own_text = own_version if own_version is not None else _own_version()
+        own = parse_version(own_text)
+        if own is None or own >= minimum:
+            return
+        with _lock:
+            if _warned:
+                return
+            _warned = True
+        warnings.warn(
+            warning_message(PACKAGE_NAME, str(own_text), ".".join(map(str, minimum))),
+            SdkVersionWarning,
+            stacklevel=stacklevel,
+        )
+    except Exception:
+        # The check must never affect the call that triggered it.
+        pass

vedika_agent/client.py

@@ -0,0 +1,401 @@
+"""HTTP client for the Vedika agent harness.
+
+Talks to a harness-server (see vedika-harness/docs/CONTRACT.md) over the
+UI Message Stream v1 wire. The default transport uses ``httpx.AsyncClient``;
+callers can inject any object with a compatible ``stream`` / ``post`` /
+``get`` interface.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Dict,
+    Mapping,
+    Optional,
+)
+
+from ._min_sdk import check_min_sdk_header
+from .errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    VedikaAgentError,
+)
+from .stream import (
+    Turn,
+    assert_ui_message_stream,
+    parse_chunk,
+)
+from .types import (
+    CancelTurnOptions,
+    CreateThreadOptions,
+    MemoryToggles,
+    ResumeTurnOptions,
+    SendTurnOptions,
+    Thread,
+    TurnInput,
+)
+
+# Header names that callers are not allowed to override.
+RESERVED_HEADERS = frozenset(
+    {"authorization", "accept", "content-type", "idempotency-key", "last-event-id",
+     "x-vercel-ai-ui-message-stream"}
+)
+
+
+def _uuid4() -> str:
+    return str(uuid.uuid4())
+
+
+def _filter_headers(extra: Optional[Mapping[str, str]]) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    if not extra:
+        return out
+    for key, value in extra.items():
+        if key.lower() in RESERVED_HEADERS:
+            continue
+        out[key] = value
+    return out
+
+
+@dataclass
+class VedikaAgentConfig:
+    base_url: str
+    api_key: str
+    default_headers: Dict[str, str] = field(default_factory=dict)
+
+
+class _HttpResponse:
+    __slots__ = ("status", "headers", "body", "_stream_factory")
+
+    def __init__(
+        self,
+        status: int,
+        headers: Mapping[str, str],
+        body: bytes,
+        stream: Optional[Callable[[int], AsyncIterator[bytes]]] = None,
+    ) -> None:
+        self.status = status
+        self.headers = dict(headers)
+        self.body = body
+        self._stream_factory = stream
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    async def text(self) -> str:
+        return self.body.decode("utf-8", errors="replace")
+
+    async def json(self) -> Any:
+        import json
+
+        return json.loads(self.body.decode("utf-8"))
+
+    def iter_bytes(self) -> AsyncIterator[bytes]:
+        if self._stream_factory is None:
+            async def _empty() -> AsyncIterator[bytes]:
+                if False:
+                    yield b""
+            return _empty()
+        return self._stream_factory(self.status)
+
+
+class _HttpTransport:
+    """Minimal async transport. Default uses ``httpx.AsyncClient``."""
+
+    def __init__(self) -> None:
+        try:
+            import httpx  # noqa: F401  - presence check
+            self._has_httpx = True
+        except ImportError:  # pragma: no cover
+            self._has_httpx = False
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        body: Optional[bytes] = None,
+        stream: bool = False,
+        timeout: float = 60.0,
+    ) -> _HttpResponse:
+        if not self._has_httpx:  # pragma: no cover
+            raise VedikaAgentError(
+                "no async HTTP transport available; install httpx or inject a custom transport",
+            )
+        import httpx
+
+        if stream:
+            # The client and the response must outlive this call: the caller
+            # reads the body later, chunk by chunk. Both are closed when the
+            # stream is exhausted, abandoned or fails.
+            client = httpx.AsyncClient(timeout=timeout)
+            try:
+                request = client.build_request(method, url, headers=dict(headers), content=body)
+                response = await client.send(request, stream=True)
+            except BaseException:
+                await client.aclose()
+                raise
+            status = response.status_code
+            hdrs = {k: v for k, v in response.headers.items()}
+            if not 200 <= status < 300:
+                # An error answer is small and the caller maps it from the body.
+                try:
+                    error_body = await response.aread()
+                finally:
+                    await response.aclose()
+                    await client.aclose()
+                return _HttpResponse(status, hdrs, error_body)
+
+            async def stream_factory(_status: int) -> AsyncIterator[bytes]:
+                try:
+                    async for chunk in response.aiter_bytes():
+                        if chunk:
+                            yield chunk
+                finally:
+                    await response.aclose()
+                    await client.aclose()
+
+            return _HttpResponse(status, hdrs, b"", stream=stream_factory)
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            request = client.build_request(method, url, headers=dict(headers), content=body)
+            response = await client.send(request, stream=False)
+            return _HttpResponse(
+                response.status_code,
+                {k: v for k, v in response.headers.items()},
+                response.content,
+            )
+
+
+class Transport:
+    """Protocol-style transport that callers can inject for tests.
+
+    Implementations must return an object with:
+
+    - ``status: int``
+    - ``headers: Mapping[str, str]``
+    - ``body: bytes``
+    - ``iter_bytes() -> AsyncIterator[bytes]``
+    - ``ok: bool`` (property)
+    - ``text() -> Awaitable[str]``
+    - ``json() -> Awaitable[Any]``
+    """
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        body: Optional[bytes] = None,
+        stream: bool = False,
+    ) -> _HttpResponse:  # pragma: no cover - interface only
+        raise NotImplementedError
+
+
+def _map_response_error(status: int, headers: Mapping[str, str], body: bytes) -> VedikaAgentError:
+    import json
+
+    try:
+        parsed = json.loads(body.decode("utf-8"))
+    except Exception:
+        parsed = None
+    if isinstance(parsed, dict):
+        message = str(parsed.get("message") or parsed.get("error") or "") or None
+        code = parsed.get("code")
+    else:
+        message = None
+        code = None
+    if message is None:
+        message = body.decode("utf-8", errors="replace")[:256] or "request failed"
+    if status in (401, 403):
+        return AuthenticationError(message, status=status)
+    if status in (404, 410):
+        return NotFoundError(message)
+    if status == 429:
+        retry_after = headers.get("retry-after")
+        seconds: Optional[int] = None
+        if retry_after:
+            try:
+                seconds = int(retry_after)
+            except ValueError:
+                seconds = None
+        return RateLimitError(message, status=status, retry_after_seconds=seconds)
+    if 400 <= status < 500:
+        return InvalidRequestError(message, status=status, code=code)
+    return ServerError(message, status=status, retryable=status >= 500)
+
+
+def _build_thread(payload: Mapping[str, Any]) -> Thread:
+    return Thread(
+        id=str(payload["id"]),
+        created_at=str(payload.get("createdAt") or payload.get("created_at") or ""),
+        metadata=dict(payload.get("metadata") or {}),
+    )
+
+
+class _ThreadsNamespace:
+    def __init__(self, parent: "VedikaAgent") -> None:
+        self._parent = parent
+
+    async def create(self, opts: Optional[CreateThreadOptions] = None) -> Thread:
+        opts = opts or CreateThreadOptions()
+        idem = opts.idempotency_key or _uuid4()
+        headers = self._parent._headers(opts.headers)
+        headers["idempotency-key"] = idem
+        headers["content-type"] = "application/json"
+        body_dict: Dict[str, Any] = {"metadata": dict(opts.metadata)}
+        import json
+
+        res = await self._parent._request(
+            "POST",
+            self._parent._url("/api/v1/agent/threads"),
+            headers=headers,
+            body=json.dumps(body_dict).encode("utf-8"),
+            stream=False,
+        )
+        if not res.ok:
+            raise _map_response_error(res.status, res.headers, res.body)
+        try:
+            payload = await res.json()
+        except Exception as exc:
+            raise ProtocolError("response body is not valid JSON") from exc
+        return _build_thread(payload)
+
+    async def send_turn(
+        self,
+        thread_id: str,
+        input: TurnInput,
+        opts: Optional[SendTurnOptions] = None,
+    ) -> Turn:
+        opts = opts or SendTurnOptions()
+        idem = opts.idempotency_key or _uuid4()
+        headers = self._parent._headers(opts.headers)
+        headers["idempotency-key"] = idem
+        headers["accept"] = "text/event-stream"
+        headers["content-type"] = "application/json"
+        if opts.model:
+            headers["x-vedika-model"] = opts.model
+        if opts.memory:
+            if not isinstance(opts.memory, MemoryToggles):
+                raise VedikaAgentError("memory option must be a MemoryToggles instance")
+            headers["x-vedika-memory-old"] = "true" if opts.memory.old_memory else "false"
+            headers["x-vedika-memory-sensitive"] = "true" if opts.memory.sensitive_info else "false"
+        import json
+
+        body = json.dumps({"input": input}).encode("utf-8")
+        res = await self._parent._request(
+            "POST",
+            self._parent._url(f"/api/v1/agent/threads/{thread_id}/turns"),
+            headers=headers,
+            body=body,
+            stream=True,
+        )
+        if not res.ok:
+            text = await res.text()
+            raise _map_response_error(res.status, res.headers, text.encode("utf-8"))
+        assert_ui_message_stream(res.headers)
+        turn_id = res.headers.get("x-vedika-turn-id") or "pending"
+        return Turn(
+            turn_id=turn_id,
+            thread_id=thread_id,
+            source=res.iter_bytes(),
+            cancel=lambda: self.cancel_turn(turn_id),
+        )
+
+    async def resume_turn(self, turn_id: str, opts: ResumeTurnOptions) -> Turn:
+        headers = self._parent._headers(opts.headers)
+        headers["accept"] = "text/event-stream"
+        headers["last-event-id"] = opts.last_event_id
+        res = await self._parent._request(
+            "GET",
+            self._parent._url(f"/api/v1/agent/turns/{turn_id}/events"),
+            headers=headers,
+            stream=True,
+        )
+        if not res.ok:
+            text = await res.text()
+            raise _map_response_error(res.status, res.headers, text.encode("utf-8"))
+        assert_ui_message_stream(res.headers)
+        thread_id = res.headers.get("x-vedika-thread-id") or "unknown"
+        return Turn(
+            turn_id=turn_id,
+            thread_id=thread_id,
+            source=res.iter_bytes(),
+            cancel=lambda: self.cancel_turn(turn_id),
+        )
+
+    async def cancel_turn(
+        self,
+        turn_id: str,
+        opts: Optional[CancelTurnOptions] = None,
+    ) -> None:
+        opts = opts or CancelTurnOptions()
+        headers = self._parent._headers(opts.headers)
+        res = await self._parent._request(
+            "POST",
+            self._parent._url(f"/api/v1/agent/turns/{turn_id}/cancel"),
+            headers=headers,
+            stream=False,
+        )
+        if not res.ok and res.status not in (404, 410):
+            raise _map_response_error(res.status, res.headers, res.body)
+
+
+class VedikaAgent:
+    """Top-level client. Construct with {@link create_agent}."""
+
+    def __init__(
+        self,
+        config: VedikaAgentConfig,
+        *,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self._config = config
+        self._transport: Any = transport or _HttpTransport()
+        self.threads = _ThreadsNamespace(self)
+
+    async def _request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Single choke point: every HTTP response the SDK receives passes here."""
+        res = await self._transport.request(method, url, **kwargs)
+        check_min_sdk_header(getattr(res, "headers", None))
+        return res
+
+    def _url(self, path: str) -> str:
+        from urllib.parse import urljoin
+
+        return urljoin(self._config.base_url + "/", path.lstrip("/"))
+
+    def _headers(self, extra: Optional[Mapping[str, str]]) -> Dict[str, str]:
+        out: Dict[str, str] = {
+            "authorization": f"Bearer {self._config.api_key}",
+            **self._config.default_headers,
+        }
+        out.update(_filter_headers(extra))
+        return out
+
+
+def create_agent(
+    base_url: str,
+    api_key: str,
+    *,
+    default_headers: Optional[Mapping[str, str]] = None,
+    transport: Optional[Transport] = None,
+) -> VedikaAgent:
+    config = VedikaAgentConfig(
+        base_url=base_url,
+        api_key=api_key,
+        default_headers=dict(default_headers or {}),
+    )
+    return VedikaAgent(config, transport=transport)