Feat: Platform V2 SDK

Author: jlsajfj

src/textql/__init__.py

@@ -9,6 +9,7 @@
     RateLimitError,
     TextQLError,
 )
+from ._streaming import Stream
 from ._version import __version__
 
 __all__ = [
@@ -19,6 +20,7 @@
     "NotFoundError",
     "PermissionDeniedError",
     "RateLimitError",
+    "Stream",
     "TextQL",
     "TextQLError",
     "__version__",

src/textql/_client.py

@@ -1,22 +1,37 @@
 from __future__ import annotations
 
 import os
-from typing import Any
+from typing import Any, NoReturn
 
 import httpx
 
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._streaming import Stream
 from ._version import __version__
+from .resources.chat import Chat
+from .resources.connectors import Connectors
+from .resources.playbooks import Playbooks
+from .resources.sandbox import Sandbox
 
-DEFAULT_BASE_URL = "https://api.textql.com"
+DEFAULT_BASE_URL = "https://app.textql.com"
 DEFAULT_TIMEOUT = 60.0
 
 
 class TextQL:
-    """Synchronous client for the TextQL Platform API.
+    """Synchronous client for the TextQL v2 Platform API."""
 
-    Resource clients (`chat`, `playbooks`, `sandbox`, `connectors`) are stubs
-    in v0.1.0 — they will be filled in as the v2 SDK takes shape.
-    """
+    chat: Chat
+    connectors: Connectors
+    playbooks: Playbooks
+    sandbox: Sandbox
 
     def __init__(
         self,
@@ -28,26 +43,88 @@ def __init__(
     ) -> None:
         key = api_key or os.environ.get("TEXTQL_API_KEY")
         if not key:
-            raise ValueError(
-                "No API key provided. Pass api_key=... or set TEXTQL_API_KEY in the environment."
-            )
-
+            raise ValueError("No API key provided. Pass api_key=... or set TEXTQL_API_KEY.")
         self.api_key = key
-        resolved_base = base_url or os.environ.get("TEXTQL_BASE_URL") or DEFAULT_BASE_URL
-        self.base_url = resolved_base.rstrip("/")
+
+        resolved = base_url or os.environ.get("TEXTQL_BASE_URL") or DEFAULT_BASE_URL
+        resolved = resolved.rstrip("/")
+        if not resolved.startswith(("http://", "https://")):
+            resolved = f"https://{resolved}"
+        self.base_url = resolved
+
         self._http = http_client or httpx.Client(
             base_url=self.base_url,
             timeout=timeout,
             headers=self._default_headers(),
         )
 
+        self.chat = Chat(self)
+        self.connectors = Connectors(self)
+        self.playbooks = Playbooks(self)
+        self.sandbox = Sandbox(self)
+
     def _default_headers(self) -> dict[str, str]:
         return {
             "Authorization": f"Bearer {self.api_key}",
             "User-Agent": f"textql-python/{__version__}",
             "Accept": "application/json",
         }
 
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            resp = self._http.request(method, path, **kwargs)
+        except httpx.TimeoutException as e:
+            raise APITimeoutError(str(e)) from e
+        except httpx.ConnectError as e:
+            raise APIConnectionError(str(e)) from e
+
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+
+        if not resp.content:
+            return None
+        return resp.json()
+
+    def _stream_request(self, method: str, path: str, **kwargs: Any) -> Stream:
+        try:
+            req = self._http.build_request(method, path, **kwargs)
+            resp = self._http.send(req, stream=True)
+        except httpx.TimeoutException as e:
+            raise APITimeoutError(str(e)) from e
+        except httpx.ConnectError as e:
+            raise APIConnectionError(str(e)) from e
+
+        if resp.status_code >= 400:
+            resp.read()
+            resp.close()
+            self._raise_for_status(resp)
+
+        return Stream(resp)
+
+    def _raise_for_status(self, response: httpx.Response) -> NoReturn:
+        message = response.text
+        request_id: str | None = None
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                error = body.get("error")
+                if isinstance(error, dict):
+                    message = error.get("message", message)
+                    request_id = error.get("request")
+        except Exception:
+            pass
+
+        status = response.status_code
+        if status == 401:
+            raise AuthenticationError(message, status_code=status, request_id=request_id)
+        if status == 403:
+            raise PermissionDeniedError(message, status_code=status, request_id=request_id)
+        if status == 404:
+            raise NotFoundError(message, status_code=status, request_id=request_id)
+        if status == 429:
+            raise RateLimitError(message, status_code=status, request_id=request_id)
+        raise APIError(message, status_code=status, request_id=request_id)
+
     def close(self) -> None:
         self._http.close()
 

src/textql/_streaming.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+
+class Stream:
+    """Iterator over Server-Sent Events from a streaming response."""
+
+    def __init__(self, response: Any) -> None:
+        self._response = response
+        self._iterator = self._parse_sse()
+
+    def _parse_sse(self) -> Iterator[dict[str, Any]]:
+        for line in self._response.iter_lines():
+            if line.startswith("data: "):
+                yield json.loads(line[6:])
+
+    def __iter__(self) -> Stream:
+        return self
+
+    def __next__(self) -> dict[str, Any]:
+        return next(self._iterator)
+
+    def close(self) -> None:
+        self._response.close()
+
+    def __enter__(self) -> Stream:
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()

src/textql/resources/__init__.py

@@ -0,0 +1,6 @@
+from .chat import Chat
+from .connectors import Connectors
+from .playbooks import Playbooks
+from .sandbox import Sandbox
+
+__all__ = ["Chat", "Connectors", "Playbooks", "Sandbox"]

src/textql/resources/chat.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Union
+
+if TYPE_CHECKING:
+    from .._client import TextQL
+    from .._streaming import Stream
+
+FileInput = Union[str, Path, "tuple[str, bytes]"]
+
+
+class Chat:
+    def __init__(self, client: TextQL) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        search_term: str | None = None,
+        sort_by: str | None = None,
+        sort_direction: str | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        if search_term is not None:
+            params["search_term"] = search_term
+        if sort_by is not None:
+            params["sort_by"] = sort_by
+        if sort_direction is not None:
+            params["sort_direction"] = sort_direction
+        return self._client._request("GET", "/v2/chats", params=params)
+
+    def create(
+        self,
+        question: str,
+        *,
+        chat_id: str | None = None,
+        connector_ids: list[int] | None = None,
+        tools: dict[str, Any] | None = None,
+        files: list[FileInput] | None = None,
+    ) -> Any:
+        if files:
+            return self._create_multipart(
+                question, chat_id=chat_id, connector_ids=connector_ids, files=files
+            )
+        body: dict[str, Any] = {"question": question}
+        if chat_id is not None:
+            body["chat_id"] = chat_id
+        if connector_ids is not None:
+            body["connector_ids"] = connector_ids
+        if tools is not None:
+            body["tools"] = tools
+        return self._client._request("POST", "/v2/chats", json=body)
+
+    def _create_multipart(
+        self,
+        question: str,
+        *,
+        chat_id: str | None = None,
+        connector_ids: list[int] | None = None,
+        files: list[FileInput],
+    ) -> Any:
+        fields: list[tuple[str, str]] = [("question", question)]
+        if chat_id is not None:
+            fields.append(("chat_id", chat_id))
+        if connector_ids is not None:
+            for cid in connector_ids:
+                fields.append(("connector_ids", str(cid)))
+
+        file_tuples: list[tuple[str, tuple[str, bytes]]] = []
+        for f in files:
+            if isinstance(f, tuple):
+                file_tuples.append(("files", f))
+            else:
+                p = Path(f)
+                file_tuples.append(("files", (p.name, p.read_bytes())))
+
+        return self._client._request("POST", "/v2/chats", data=fields, files=file_tuples)
+
+    def get(self, chat_id: str) -> Any:
+        return self._client._request("GET", f"/v2/chats/{chat_id}")
+
+    def stream(
+        self,
+        question: str,
+        *,
+        chat_id: str | None = None,
+        connector_ids: list[int] | None = None,
+        tools: dict[str, Any] | None = None,
+    ) -> Stream:
+        body: dict[str, Any] = {"question": question}
+        if chat_id is not None:
+            body["chat_id"] = chat_id
+        if connector_ids is not None:
+            body["connector_ids"] = connector_ids
+        if tools is not None:
+            body["tools"] = tools
+        return self._client._stream_request("POST", "/v2/chats/stream", json=body)
+
+    def cancel(self, chat_id: str) -> Any:
+        return self._client._request("POST", f"/v2/chats/{chat_id}/cancel")

src/textql/resources/connectors.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .._client import TextQL
+
+
+class Connectors:
+    def __init__(self, client: TextQL) -> None:
+        self._client = client
+
+    def list(self) -> Any:
+        return self._client._request("GET", "/v2/connectors")