sveda-python-sdk 0.1.0__tar.gz

sveda_python_sdk-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,37 @@
+# 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/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "sveda-python-sdk"
+version = "0.1.0"
+description = "Python SDK for the Sveda AI sidecar HTTP API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Neresson" },
+]
+keywords = ["sveda", "ai", "copilot", "sdk", "client"]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/neresson/sveda-python-sdk"
+Repository = "https://github.com/neresson/sveda-python-sdk"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sveda_python_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sveda_python_sdk-0.1.0/src/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_python_sdk-0.1.0/src/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_python_sdk-0.1.0/src/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_python_sdk-0.1.0/src/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_python_sdk-0.1.0/src/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_python_sdk-0.1.0/src/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/src/sveda_python_sdk.egg-info/PKG-INFO

@@ -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/src/sveda_python_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/sveda/__init__.py
+src/sveda/client.py
+src/sveda/exceptions.py
+src/sveda/session.py
+src/sveda/streaming.py
+src/sveda/types.py
+src/sveda_python_sdk.egg-info/PKG-INFO
+src/sveda_python_sdk.egg-info/SOURCES.txt
+src/sveda_python_sdk.egg-info/dependency_links.txt
+src/sveda_python_sdk.egg-info/requires.txt
+src/sveda_python_sdk.egg-info/top_level.txt
+tests/test_client.py

sveda_python_sdk-0.1.0/src/sveda_python_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sveda_python_sdk-0.1.0/src/sveda_python_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27

sveda_python_sdk-0.1.0/src/sveda_python_sdk.egg-info/top_level.txt

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

sveda_python_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import json
+import unittest
+
+import httpx
+
+from sveda import SvedaClient, start_host_session
+from sveda.exceptions import APIError, AuthenticationError
+
+
+def _client(
+    handler: httpx.MockTransport | httpx.Client,
+    *,
+    host_api_key: str | None = "host-secret",
+    embed_token: str | None = None,
+) -> SvedaClient:
+    http_client = (
+        handler
+        if isinstance(handler, httpx.Client)
+        else httpx.Client(transport=handler)
+    )
+    return SvedaClient(
+        "https://sveda.test",
+        host_api_key=host_api_key,
+        embed_token=embed_token,
+        http_client=http_client,
+    )
+
+
+class ClientTest(unittest.TestCase):
+    def test_create_token_sends_bearer_auth(self) -> None:
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            captured["method"] = request.method
+            captured["path"] = request.url.path
+            captured["authorization"] = request.headers.get("Authorization")
+            captured["body"] = json.loads(request.content)
+            return httpx.Response(
+                200,
+                json={
+                    "token": "sveda_embed_test",
+                    "visitor_id": "visitor-1",
+                    "expires_in": 3600,
+                    "appearance": {"accent": "#c45c26"},
+                },
+            )
+
+        client = _client(httpx.MockTransport(handler))
+        try:
+            token = client.embed.create_token(
+                visitor_id="visitor-1",
+                host_mcp_url="https://app.test/mcp/sveda",
+                host_mcp_token="mcp-token",
+            )
+        finally:
+            client.close()
+
+        self.assertEqual(token.token, "sveda_embed_test")
+        self.assertEqual(token.visitor_id, "visitor-1")
+        self.assertEqual(token.expires_in, 3600)
+        self.assertEqual(token.appearance, {"accent": "#c45c26"})
+        self.assertEqual(captured["method"], "POST")
+        self.assertEqual(captured["path"], "/sveda/embed/token")
+        self.assertEqual(captured["authorization"], "Bearer host-secret")
+        self.assertEqual(
+            captured["body"],
+            {
+                "visitor_id": "visitor-1",
+                "host_mcp_url": "https://app.test/mcp/sveda",
+                "host_mcp_token": "mcp-token",
+            },
+        )
+
+    def test_create_streamed_parses_events_and_skips_done(self) -> None:
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            captured["method"] = request.method
+            captured["path"] = request.url.path
+            captured["accept"] = request.headers.get("Accept")
+            captured["embed"] = request.headers.get("X-Sveda-Embed-Token")
+            captured["body"] = json.loads(request.content)
+            return httpx.Response(
+                200,
+                text=(
+                    'data: {"type":"message.start"}\n\n'
+                    'data: {"type":"text.delta","delta":"Hi"}\n\n'
+                    "data: [DONE]\n\n"
+                ),
+            )
+
+        client = _client(
+            httpx.MockTransport(handler),
+            host_api_key=None,
+            embed_token="embed-token",
+        )
+        try:
+            events = list(
+                client.chat.create_streamed(
+                    messages=[{"role": "user", "content": "Hi"}],
+                    chat_id="c1",
+                )
+            )
+        finally:
+            client.close()
+
+        self.assertEqual(len(events), 2)
+        self.assertEqual(events[0].type, "message.start")
+        self.assertEqual(events[1].type, "text.delta")
+        self.assertEqual(events[1].delta, "Hi")
+        self.assertEqual(captured["method"], "POST")
+        self.assertEqual(captured["path"], "/sveda/stream")
+        self.assertEqual(captured["accept"], "application/vnd.sveda.stream+json")
+        self.assertEqual(captured["embed"], "embed-token")
+        self.assertEqual(
+            captured["body"],
+            {
+                "messages": [{"role": "user", "content": "Hi"}],
+                "chatId": "c1",
+            },
+        )
+
+    def test_401_raises_authentication_error(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(401, json={"message": "nope"})
+
+        client = _client(httpx.MockTransport(handler))
+        try:
+            with self.assertRaises(AuthenticationError) as ctx:
+                client.embed.create_token(visitor_id="visitor-1")
+        finally:
+            client.close()
+
+        self.assertIn("401", str(ctx.exception))
+
+    def test_non_auth_error_uses_json_message(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(422, json={"message": "visitor_id is too long"})
+
+        client = _client(httpx.MockTransport(handler))
+        try:
+            with self.assertRaises(APIError) as ctx:
+                client.embed.create_token(visitor_id="visitor-1")
+        finally:
+            client.close()
+
+        self.assertEqual(str(ctx.exception), "visitor_id is too long")
+        self.assertEqual(ctx.exception.status_code, 422)
+
+    def test_start_host_session(self) -> None:
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            captured["authorization"] = request.headers.get("Authorization")
+            captured["body"] = json.loads(request.content)
+            captured["path"] = request.url.path
+            return httpx.Response(
+                200,
+                json={
+                    "token": "sveda_embed_host",
+                    "visitor_id": "flask-playground",
+                    "expires_in": 1200,
+                },
+            )
+
+        http_client = httpx.Client(transport=httpx.MockTransport(handler))
+        try:
+            session = start_host_session(
+                "https://sveda.test/",
+                "host-secret",
+                "flask-playground",
+                http_client=http_client,
+            )
+        finally:
+            http_client.close()
+
+        self.assertEqual(
+            session,
+            {
+                "origin": "https://sveda.test",
+                "token": "sveda_embed_host",
+                "expires_in": 1200,
+                "appearance": None,
+            },
+        )
+        self.assertEqual(captured["authorization"], "Bearer host-secret")
+        self.assertEqual(captured["path"], "/sveda/embed/token")
+        self.assertEqual(captured["body"], {"visitor_id": "flask-playground"})
+
+    def test_message_and_histories(self) -> None:
+        def handler(request: httpx.Request) -> httpx.Response:
+            if request.method == "POST" and request.url.path == "/sveda/message":
+                return httpx.Response(
+                    200,
+                    json={
+                        "explanation": "Hello",
+                        "tokens_used": 12,
+                        "chat_id": "chat-1",
+                    },
+                )
+            if request.method == "GET" and request.url.path == "/sveda/chat-histories":
+                return httpx.Response(200, json={"histories": []})
+            return httpx.Response(404, json={"message": "unexpected"})
+
+        client = _client(
+            httpx.MockTransport(handler),
+            host_api_key=None,
+            embed_token="embed-token",
+        )
+        try:
+            message = client.chat.create(
+                messages=[{"role": "user", "content": "Hello"}],
+                chat_id="chat-1",
+            )
+            histories = client.histories.list()
+        finally:
+            client.close()
+
+        self.assertEqual(message.explanation, "Hello")
+        self.assertEqual(message.tokens_used, 12)
+        self.assertEqual(message.chat_id, "chat-1")
+        self.assertIn("histories", histories)
+
+
+if __name__ == "__main__":
+    unittest.main()