sveda-python-sdk 0.1.0__py3-none-any.whl

sveda/__init__.py

@@ -0,0 +1,26 @@
+from sveda.client import SvedaClient
+from sveda.exceptions import (
+    APIError,
+    AuthenticationError,
+    TransportError,
+    UnserializableResponse,
+    SvedaError,
+)
+from sveda.session import start_host_session
+from sveda.streaming import StreamEvent
+from sveda.types import EmbedToken, Message
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "EmbedToken",
+    "Message",
+    "StreamEvent",
+    "TransportError",
+    "UnserializableResponse",
+    "SvedaClient",
+    "SvedaError",
+    "start_host_session",
+]
+
+__version__ = "0.1.0"

sveda/client.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from sveda.exceptions import (
+    APIError,
+    AuthenticationError,
+    TransportError,
+    UnserializableResponse,
+)
+from sveda.streaming import StreamEvent, iter_sse_lines
+from sveda.types import EmbedToken, Message
+
+ACCEPT_JSON = "application/json"
+ACCEPT_STREAM = "application/vnd.sveda.stream+json"
+
+
+class SvedaClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        host_api_key: str | None = None,
+        embed_token: str | None = None,
+        timeout: float = 30.0,
+        connect_timeout: float = 5.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._host_api_key = host_api_key or None
+        self._embed_token = embed_token or None
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(
+            timeout=httpx.Timeout(timeout, connect=connect_timeout),
+        )
+        self.embed = EmbedResource(self)
+        self.chat = ChatResource(self)
+        self.histories = HistoriesResource(self)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> SvedaClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    def _auth_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self._host_api_key is not None:
+            headers["Authorization"] = f"Bearer {self._host_api_key}"
+        if self._embed_token is not None:
+            headers["X-Sveda-Embed-Token"] = self._embed_token
+        return headers
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        payload: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        headers = {**self._auth_headers(), "Accept": ACCEPT_JSON}
+        json_payload: Mapping[str, Any] | None = dict(payload) if payload else None
+        if method.upper() in {"GET", "HEAD", "DELETE"}:
+            json_payload = None
+        elif json_payload is None:
+            json_payload = {}
+        try:
+            response = self._http.request(
+                method,
+                self._url(path),
+                json=json_payload,
+                headers=headers,
+            )
+        except httpx.RequestError as exc:
+            raise TransportError(str(exc)) from exc
+        return self._decode_json(response)
+
+    def request_stream(
+        self,
+        method: str,
+        path: str,
+        payload: Mapping[str, Any] | None = None,
+    ) -> Iterator[StreamEvent]:
+        headers = {
+            **self._auth_headers(),
+            "Accept": ACCEPT_STREAM,
+            "Content-Type": "application/json",
+        }
+        try:
+            with self._http.stream(
+                method,
+                self._url(path),
+                json=dict(payload or {}),
+                headers=headers,
+            ) as response:
+                if response.status_code < 200 or response.status_code >= 300:
+                    response.read()
+                    self._raise_for_status(response)
+                yield from iter_sse_lines(response.iter_lines())
+        except httpx.RequestError as exc:
+            raise TransportError(str(exc)) from exc
+
+    def _decode_json(self, response: httpx.Response) -> dict[str, Any]:
+        self._raise_for_status(response)
+        if response.content == b"":
+            return {}
+        try:
+            decoded = response.json()
+        except ValueError as exc:
+            raise UnserializableResponse(
+                "Unable to decode Sveda API response as JSON."
+            ) from exc
+        if not isinstance(decoded, dict):
+            raise UnserializableResponse("Unable to decode Sveda API response as JSON.")
+        return decoded
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        status = response.status_code
+        if status in {401, 403}:
+            raise AuthenticationError(
+                f"Sveda API authentication failed with status {status}"
+            )
+        if status < 200 or status >= 300:
+            data: Any = None
+            try:
+                data = response.json()
+            except ValueError:
+                data = None
+            message = f"Sveda API request failed with status {status}"
+            if isinstance(data, dict) and isinstance(data.get("message"), str):
+                message = data["message"]
+            raise APIError(
+                message,
+                status_code=status,
+                response=data if isinstance(data, dict) else None,
+            )
+
+
+class EmbedResource:
+    def __init__(self, client: SvedaClient) -> None:
+        self._client = client
+
+    def create_token(
+        self,
+        visitor_id: str | None = None,
+        *,
+        host_mcp_url: str | None = None,
+        host_mcp_token: str | None = None,
+    ) -> EmbedToken:
+        payload: dict[str, Any] = {}
+        if visitor_id:
+            payload["visitor_id"] = visitor_id
+        if host_mcp_url and host_mcp_token:
+            payload["host_mcp_url"] = host_mcp_url
+            payload["host_mcp_token"] = host_mcp_token
+        return EmbedToken.from_dict(
+            self._client.request_json("POST", "/sveda/embed/token", payload)
+        )
+
+    def config(self) -> dict[str, Any]:
+        return self._client.request_json("GET", "/sveda/embed/config")
+
+
+class ChatResource:
+    def __init__(self, client: SvedaClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        chat_id: str | None = None,
+        **extra: Any,
+    ) -> Message:
+        return Message.from_dict(
+            self._client.request_json(
+                "POST",
+                "/sveda/message",
+                _chat_payload(messages, chat_id, extra),
+            )
+        )
+
+    def create_streamed(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        chat_id: str | None = None,
+        **extra: Any,
+    ) -> Iterator[StreamEvent]:
+        return self._client.request_stream(
+            "POST",
+            "/sveda/stream",
+            _chat_payload(messages, chat_id, extra),
+        )
+
+
+class HistoriesResource:
+    def __init__(self, client: SvedaClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request_json("GET", "/sveda/chat-histories")
+
+    def get(self, chat_id: str) -> dict[str, Any]:
+        return self._client.request_json("GET", _history_path(chat_id))
+
+    def rename(self, chat_id: str, title: str) -> dict[str, Any]:
+        return self._client.request_json(
+            "PATCH",
+            _history_path(chat_id),
+            {"title": title},
+        )
+
+    def delete(self, chat_id: str) -> dict[str, Any]:
+        return self._client.request_json("DELETE", _history_path(chat_id))
+
+
+def _history_path(chat_id: str) -> str:
+    return "/sveda/chat-histories/" + quote(chat_id, safe="")
+
+
+def _chat_payload(
+    messages: list[dict[str, Any]],
+    chat_id: str | None,
+    extra: Mapping[str, Any],
+) -> dict[str, Any]:
+    payload = dict(extra)
+    payload["messages"] = messages
+    if "client_tools" in payload:
+        payload["clientTools"] = payload.pop("client_tools")
+    if "chat_id" in payload:
+        payload["chatId"] = payload.pop("chat_id")
+    if chat_id is not None:
+        payload["chatId"] = chat_id
+    return payload

sveda/exceptions.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+
+class SvedaError(Exception):
+    pass
+
+
+class AuthenticationError(SvedaError):
+    pass
+
+
+class APIError(SvedaError):
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 0,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class TransportError(SvedaError):
+    pass
+
+
+class UnserializableResponse(SvedaError):
+    pass

sveda/session.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from sveda.client import SvedaClient
+from sveda.exceptions import APIError
+
+
+def start_host_session(
+    base_url: str,
+    host_api_key: str,
+    visitor_id: str,
+    *,
+    host_mcp_url: str | None = None,
+    host_mcp_token: str | None = None,
+    http_client: httpx.Client | None = None,
+) -> dict[str, Any]:
+    origin = base_url.rstrip("/")
+    with SvedaClient(
+        origin,
+        host_api_key=host_api_key,
+        http_client=http_client,
+    ) as client:
+        token = client.embed.create_token(
+            visitor_id=visitor_id,
+            host_mcp_url=host_mcp_url,
+            host_mcp_token=host_mcp_token,
+        )
+    if token.token == "":
+        raise APIError("Sidecar returned an empty embed token.")
+    return {
+        "origin": origin,
+        "token": token.token,
+        "expires_in": token.expires_in,
+        "appearance": token.appearance,
+    }

sveda/streaming.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+SSE_DONE_LINE = "data: [DONE]"
+
+STREAM_EVENTS = frozenset(
+    {
+        "message.start",
+        "text.delta",
+        "reasoning.delta",
+        "tool.call",
+        "tool.result",
+        "tool.progress",
+        "context.usage",
+        "chat.title",
+        "max_steps",
+        "message.end",
+        "error",
+    }
+)
+
+
+@dataclass(frozen=True)
+class StreamEvent:
+    type: str
+    payload: dict[str, Any]
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self.payload[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.payload
+
+
+def parse_sse_line(line: str) -> StreamEvent | None:
+    trimmed = line.strip()
+    if not trimmed.startswith("data:"):
+        return None
+
+    payload = trimmed[5:].strip()
+    if payload == "" or payload == "[DONE]":
+        return None
+
+    try:
+        decoded = json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+
+    if not isinstance(decoded, dict):
+        return None
+
+    event_type = decoded.get("type")
+    if not isinstance(event_type, str) or event_type not in STREAM_EVENTS:
+        return None
+
+    return StreamEvent(type=event_type, payload=decoded)
+
+
+def iter_sse_lines(lines: Iterable[str]) -> Iterator[StreamEvent]:
+    for line in lines:
+        event = parse_sse_line(line)
+        if event is not None:
+            yield event
+
+
+def iter_sse_text(content: str) -> Iterator[StreamEvent]:
+    return iter_sse_lines(content.splitlines())

sveda/types.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class EmbedToken:
+    token: str
+    visitor_id: str
+    expires_in: int
+    appearance: dict[str, Any] | None = None
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> EmbedToken:
+        appearance = payload.get("appearance")
+        raw_expires = payload.get("expires_in", 3600)
+        if raw_expires is None:
+            raw_expires = 3600
+        return cls(
+            token=str(payload.get("token", "")),
+            visitor_id=str(payload.get("visitor_id", "")),
+            expires_in=max(60, int(raw_expires)),
+            appearance=appearance if isinstance(appearance, dict) else None,
+        )
+
+
+@dataclass(frozen=True)
+class Message:
+    explanation: str
+    tokens_used: int
+    chat_id: str
+    payload: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> Message:
+        data = dict(payload)
+        return cls(
+            explanation=str(data.get("explanation", "")),
+            tokens_used=int(data.get("tokens_used") or 0),
+            chat_id=str(data.get("chat_id", "")),
+            payload=data,
+        )

sveda_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: sveda-python-sdk
+Version: 0.1.0
+Summary: Python SDK for the Sveda AI sidecar HTTP API
+Author: Neresson
+License: MIT
+Project-URL: Homepage, https://github.com/neresson/sveda-python-sdk
+Project-URL: Repository, https://github.com/neresson/sveda-python-sdk
+Keywords: sveda,ai,copilot,sdk,client
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# sveda-python-sdk
+
+Python SDK for the Sveda AI sidecar HTTP API.
+
+PyPI: `sveda-python-sdk` (import `sveda`)
+
+## Install
+
+```bash
+pip install sveda-python-sdk
+```
+
+## Usage
+
+```python
+from sveda import SvedaClient, start_host_session
+
+client = SvedaClient(base_url="http://127.0.0.1:8787", host_api_key="...")
+tok = client.embed.create_token(visitor_id="flask-playground")
+
+client = SvedaClient(base_url="http://127.0.0.1:8787", embed_token=tok.token)
+for event in client.chat.create_streamed(
+    messages=[{"role": "user", "content": "Hi"}],
+    chat_id="c1",
+):
+    print(event.type)
+
+session = start_host_session(
+    "http://127.0.0.1:8787",
+    "host-api-key",
+    "flask-playground",
+)
+```
+
+## License
+
+MIT

sveda_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sveda/__init__.py,sha256=faNMeGEazyc97TlAV8JCqfD1u117Zipi6rOREjguesE,550
+sveda/client.py,sha256=gXRTDQzqHMdlFszN4SK3w2ueSR6GL7d_-qp3J8kmDoc,7673
+sveda/exceptions.py,sha256=f84_rCf6wKuOrGD3Y9tIznBwSK7MSlMsyzHx8qzMvb8,494
+sveda/session.py,sha256=rH0HGmr_ntZc-tLGjnYZGxF89yHHl_gmINTIfwlbpRc,960
+sveda/streaming.py,sha256=AMzwhQSYOfyG4ZFwCVgQyK8uZD-RYunFUD930YSV-6U,1695
+sveda/types.py,sha256=-Aweg3yZ6yfYNU9gUC9EkbmS_1Nil0_BQvh-UI15y9I,1220
+sveda_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=pkspmjnwqf25g5hC9qAnQzixE9LjRIn3VCGnqMHPPl0,1078
+sveda_python_sdk-0.1.0.dist-info/METADATA,sha256=FMpdbNCjek6ihBgi_VdTRdPhEenbl_k1r8k-mXqh5AI,1170
+sveda_python_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sveda_python_sdk-0.1.0.dist-info/top_level.txt,sha256=2yL9h67M0Dppf5i_0i7gJpO53_Q1Vu63vpd_inId0HA,6
+sveda_python_sdk-0.1.0.dist-info/RECORD,,

sveda_python_sdk-0.1.0.dist-info/WHEEL

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

sveda_python_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sveda AI Contributors
+
+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.

sveda_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sveda