qca-sdk 0.0.1.dev5__tar.gz → 0.1.0__tar.gz

{qca_sdk-0.0.1.dev5 → qca_sdk-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qca-sdk
-Version: 0.0.1.dev5
+Version: 0.1.0
 Summary: Typed synchronous and asynchronous clients for Qoder Cloud Agents
 Author: Qoder
 License-Expression: MIT
@@ -44,7 +44,7 @@ The API is exposed in two modes, and each has its own client, resources, and typ
 python -m pip install qca-sdk
 ```
 
-The distribution is named `qca-sdk`; the import package is `qca`. The package is still in pre-release, so the command above resolves to the latest `0.0.1.devN` build. To work from a checkout of this repository instead:
+The distribution is named `qca-sdk`; the import package is `qca`. The package is pre-1.0, so the command above resolves to the latest `0.1.x` release. To work from a checkout of this repository instead:
 
 ```bash
 python -m pip install .
@@ -86,7 +86,7 @@ Explicit arguments take precedence over environment variables. The clients never
 
 ```python
 client = Forward(
-    access_token="your-access-token",
+    pat="your-access-token",
     base_url="https://api.qoder.com.cn/api/v1/forward",
     timeout=30.0,
     max_retries=2,
@@ -190,21 +190,29 @@ Reuse one `session_id` for the whole conversation, and reuse one idempotency key
 
 ## Resuming a stream
 
-The SDK does not reconnect a dropped stream on its own. Persist `stream.last_event_id` and pass it back as `last_event_id` on the next call; the server replays from there, so you never have to resend a message it already accepted.
+The low-level `stream()` method exposes `stream.last_event_id` but does not reconnect. Use the handwritten `resumable_stream()` helper to reconnect automatically after EOF, timeouts, transient transport failures, and retryable HTTP statuses. It checkpoints only complete events and sends the latest checkpoint as `Last-Event-ID`; close it with a context manager when finished.
 
 ```python
-from qca import APIConnectionError
+with client.sessions.events.resumable_stream(
+    session_id,
+    last_event_id=saved_event_id,
+    event_deltas=["agent.message"],
+) as stream:
+    for event in stream:
+        saved_event_id = stream.last_event_id
+        print(event.type)
+```
 
-last_event_id = None
-try:
-    with client.sessions.events.stream(session_id, last_event_id=last_event_id) as stream:
-        for event in stream:
-            last_event_id = stream.last_event_id
-            print(event.type)
-except APIConnectionError:
-    pass  # reconnect with the last_event_id recorded above
+The async form is a native async iterator and context manager; unlike `stream()`, constructing it does not require `await`:
+
+```python
+async with client.sessions.events.resumable_stream(session_id) as stream:
+    async for event in stream:
+        print(event.type)
 ```
 
+The helper retries until closed, cancelled, or it receives `session.status_terminated` / `session.deleted`. It uses jittered exponential backoff and the same HTTP retry classification as the client (in particular, `409` is not retried). It does not query event history, discard an invalid cursor, or deduplicate event IDs because multiple preview deltas may share one ID.
+
 Events are also readable after the fact through `client.sessions.events.list(session_id)`, which paginates like any other list method.
 
 ## Handling errors
@@ -390,11 +398,11 @@ For tokens that expire, pass a credential provider instead of a static token. It
 client = Forward(credential=my_credential)
 ```
 
-A static `access_token` takes precedence over a provider, and an explicit `Authorization` header takes precedence over both.
+A static `pat` takes precedence over a provider, and an explicit `Authorization` header takes precedence over both.
 
 ## Versioning
 
-This project follows [Semantic Versioning](https://semver.org). It is pre-1.0 and currently published as `0.0.1.devN`, so the public surface may still change between releases. Anything prefixed with an underscore is internal and may change at any time.
+This project follows [Semantic Versioning](https://semver.org). It is pre-1.0 and currently published as `0.1.0`, so the public surface may still change between releases. Anything prefixed with an underscore is internal and may change at any time.
 
 ```python
 import qca

{qca_sdk-0.0.1.dev5 → qca_sdk-0.1.0}/README.md

@@ -12,7 +12,7 @@ The API is exposed in two modes, and each has its own client, resources, and typ
 python -m pip install qca-sdk
 ```
 
-The distribution is named `qca-sdk`; the import package is `qca`. The package is still in pre-release, so the command above resolves to the latest `0.0.1.devN` build. To work from a checkout of this repository instead:
+The distribution is named `qca-sdk`; the import package is `qca`. The package is pre-1.0, so the command above resolves to the latest `0.1.x` release. To work from a checkout of this repository instead:
 
 ```bash
 python -m pip install .
@@ -54,7 +54,7 @@ Explicit arguments take precedence over environment variables. The clients never
 
 ```python
 client = Forward(
-    access_token="your-access-token",
+    pat="your-access-token",
     base_url="https://api.qoder.com.cn/api/v1/forward",
     timeout=30.0,
     max_retries=2,
@@ -158,21 +158,29 @@ Reuse one `session_id` for the whole conversation, and reuse one idempotency key
 
 ## Resuming a stream
 
-The SDK does not reconnect a dropped stream on its own. Persist `stream.last_event_id` and pass it back as `last_event_id` on the next call; the server replays from there, so you never have to resend a message it already accepted.
+The low-level `stream()` method exposes `stream.last_event_id` but does not reconnect. Use the handwritten `resumable_stream()` helper to reconnect automatically after EOF, timeouts, transient transport failures, and retryable HTTP statuses. It checkpoints only complete events and sends the latest checkpoint as `Last-Event-ID`; close it with a context manager when finished.
 
 ```python
-from qca import APIConnectionError
+with client.sessions.events.resumable_stream(
+    session_id,
+    last_event_id=saved_event_id,
+    event_deltas=["agent.message"],
+) as stream:
+    for event in stream:
+        saved_event_id = stream.last_event_id
+        print(event.type)
+```
 
-last_event_id = None
-try:
-    with client.sessions.events.stream(session_id, last_event_id=last_event_id) as stream:
-        for event in stream:
-            last_event_id = stream.last_event_id
-            print(event.type)
-except APIConnectionError:
-    pass  # reconnect with the last_event_id recorded above
+The async form is a native async iterator and context manager; unlike `stream()`, constructing it does not require `await`:
+
+```python
+async with client.sessions.events.resumable_stream(session_id) as stream:
+    async for event in stream:
+        print(event.type)
 ```
 
+The helper retries until closed, cancelled, or it receives `session.status_terminated` / `session.deleted`. It uses jittered exponential backoff and the same HTTP retry classification as the client (in particular, `409` is not retried). It does not query event history, discard an invalid cursor, or deduplicate event IDs because multiple preview deltas may share one ID.
+
 Events are also readable after the fact through `client.sessions.events.list(session_id)`, which paginates like any other list method.
 
 ## Handling errors
@@ -358,11 +366,11 @@ For tokens that expire, pass a credential provider instead of a static token. It
 client = Forward(credential=my_credential)
 ```
 
-A static `access_token` takes precedence over a provider, and an explicit `Authorization` header takes precedence over both.
+A static `pat` takes precedence over a provider, and an explicit `Authorization` header takes precedence over both.
 
 ## Versioning
 
-This project follows [Semantic Versioning](https://semver.org). It is pre-1.0 and currently published as `0.0.1.devN`, so the public surface may still change between releases. Anything prefixed with an underscore is internal and may change at any time.
+This project follows [Semantic Versioning](https://semver.org). It is pre-1.0 and currently published as `0.1.0`, so the public surface may still change between releases. Anything prefixed with an underscore is internal and may change at any time.
 
 ```python
 import qca

{qca_sdk-0.0.1.dev5 → qca_sdk-0.1.0}/examples/common/live.py

@@ -56,7 +56,7 @@ def read_env(path: str | Path) -> dict[str, str]:
 @dataclass
 class Config:
     mode: str
-    access_token: str = field(repr=False)
+    pat: str = field(repr=False)
     base_url: str = ""
     model: str = ""
     timeout: float = 300
@@ -89,7 +89,7 @@ class Config:
         return cls(mode, token, str(url), values.get(prefix + "MODEL", ""), timeout)
 
     def client_options(self) -> dict[str, Any]:
-        return dict(access_token=self.access_token, base_url=self.base_url, max_retries=0, timeout=30)
+        return dict(pat=self.pat, base_url=self.base_url, max_retries=0, timeout=30)
 
 
 def safe_error(error: BaseException, token: str = "") -> str:
@@ -163,7 +163,7 @@ class Run:
             try:
                 action()
             except Exception as error:
-                failures.append(f"{kind} {resource_id}: {safe_error(error, self.config.access_token)}")
+                failures.append(f"{kind} {resource_id}: {safe_error(error, self.config.pat)}")
         self.cleanups.clear()
         if failures:
             raise RuntimeError("Cleanup failed:\n" + "\n".join(failures))
@@ -314,9 +314,9 @@ def run_cli(mode: str, client_type: Any, scenarios: dict[str, Callable[[Any, Run
                     try:
                         context.cleanup()
                     except Exception as error:
-                        errors.append(safe_error(error, config.access_token))
+                        errors.append(safe_error(error, config.pat))
         except Exception as error:
-            errors.insert(0, safe_error(error, config.access_token))
+            errors.insert(0, safe_error(error, config.pat))
         results.append({"scenario": scenario, "passed": not errors, "outputs": context.outputs, "errors": errors})
         if args.output == "text":
             print(f"{scenario}: {'FAIL' if errors else 'PASS'}")

{qca_sdk-0.0.1.dev5 → qca_sdk-0.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qca-sdk"
-version = "0.0.1.dev5"
+version = "0.1.0"
 description = "Typed synchronous and asynchronous clients for Qoder Cloud Agents"
 authors = [{name = "Qoder"}]
 license = "MIT"

{qca_sdk-0.0.1.dev5 → qca_sdk-0.1.0}/src/qca/common/_base_client.py

@@ -54,7 +54,7 @@ class BaseClient:
     def _configure(
         self,
         *,
-        access_token: str | None,
+        pat: str | None,
         base_url: str | httpx.URL | None,
         timeout: float | httpx.Timeout | None,
         max_retries: int,
@@ -64,7 +64,7 @@ class BaseClient:
     ) -> None:
         if not isinstance(max_retries, int) or isinstance(max_retries, bool) or max_retries < 0:
             raise ValueError("max_retries must be a non-negative integer")
-        self.access_token = access_token if access_token is not None else os.environ.get("QODER_PAT")
+        self.pat = pat if pat is not None else os.environ.get("QODER_PAT")
         self.credential = credential
         self.base_url = httpx.URL(base_url or os.environ.get(self._base_url_env) or self._default_base_url)
         if self.base_url.scheme not in ("http", "https") or not self.base_url.host or self.base_url.userinfo:
@@ -80,7 +80,7 @@ class BaseClient:
 
     def _copy(self, *, raw: bool = False, streaming: bool = False, **overrides: Any) -> Self:
         options = dict(
-            access_token=self.access_token,
+            pat=self.pat,
             base_url=self.base_url,
             timeout=self.timeout,
             max_retries=self.max_retries,
@@ -98,16 +98,14 @@ class BaseClient:
     def with_options(
         self,
         *,
-        access_token: str | NotGiven = NOT_GIVEN,
+        pat: str | NotGiven = NOT_GIVEN,
         base_url: str | httpx.URL | NotGiven = NOT_GIVEN,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
         max_retries: int | NotGiven = NOT_GIVEN,
         default_headers: Mapping[str, str] | NotGiven = NOT_GIVEN,
         default_query: Mapping[str, Any] | NotGiven = NOT_GIVEN,
     ) -> Self:
-        values: dict[str, Any] = dict(
-            access_token=access_token, base_url=base_url, timeout=timeout, max_retries=max_retries
-        )
+        values: dict[str, Any] = dict(pat=pat, base_url=base_url, timeout=timeout, max_retries=max_retries)
         if not isinstance(default_headers, NotGiven):
             values["default_headers"] = {**self.default_headers, **default_headers}
         if not isinstance(default_query, NotGiven):
@@ -120,6 +118,17 @@ class BaseClient:
     def is_closed(self) -> bool:
         return self._client.is_closed
 
+    def _validate_headers(self, headers: httpx.Headers) -> None:
+        if headers.get("Authorization"):
+            return
+        if self.credential is not None:
+            return
+
+        raise TypeError(
+            "Could not resolve authentication method. Expected one of pat or credential to be set, "
+            "or the QODER_PAT environment variable to be configured."
+        )
+
     def _headers(self, options: dict[str, Any], token: str | None) -> httpx.Headers:
         headers = httpx.Headers(
             {
@@ -134,6 +143,7 @@ class BaseClient:
         for source in (self.default_headers, options.get("headers", {})):
             for key, value in source.items():
                 headers[key] = ",".join(str(v) for v in value) if isinstance(value, (list, tuple)) else str(value)
+        self._validate_headers(headers)
         return headers
 
     def _request_args(
@@ -243,7 +253,7 @@ class SyncAPIClient(BaseClient):
     def __init__(
         self,
         *,
-        access_token: str | None = None,
+        pat: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
         max_retries: int = 2,
@@ -253,7 +263,7 @@ class SyncAPIClient(BaseClient):
         credential: Credential | None = None,
     ) -> None:
         self._configure(
-            access_token=access_token,
+            pat=pat,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -270,12 +280,7 @@ class SyncAPIClient(BaseClient):
         for attempt in range(self.max_retries + 1):
             if track_retries and attempt:
                 request.headers["X-Qoder-Retry-Count"] = str(attempt)
-            if (
-                not storage
-                and self.credential
-                and not self.access_token
-                and "Authorization" not in self.default_headers
-            ):
+            if not storage and self.credential and not self.pat and "Authorization" not in self.default_headers:
                 # Dynamic credentials can rotate between retries. Explicit request
                 # headers still take priority and are marked by request().
                 if not request.extensions.get("qca_explicit_auth"):
@@ -315,7 +320,7 @@ class SyncAPIClient(BaseClient):
         download_link: bool = False,
         file_fields: list[str] | None = None,
     ) -> Any:
-        args = self._request_args(method, path, options, self.access_token, file_fields)
+        args = self._request_args(method, path, options, self.pat, file_fields)
         if stream:
             args["headers"]["Accept"] = "text/event-stream"
         request = self._client.build_request(**args)
@@ -361,7 +366,7 @@ class AsyncAPIClient(BaseClient):
     def __init__(
         self,
         *,
-        access_token: str | None = None,
+        pat: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
         max_retries: int = 2,
@@ -371,7 +376,7 @@ class AsyncAPIClient(BaseClient):
         credential: Credential | AsyncCredential | None = None,
     ) -> None:
         self._configure(
-            access_token=access_token,
+            pat=pat,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -388,12 +393,7 @@ class AsyncAPIClient(BaseClient):
         for attempt in range(self.max_retries + 1):
             if track_retries and attempt:
                 request.headers["X-Qoder-Retry-Count"] = str(attempt)
-            if (
-                not storage
-                and self.credential
-                and not self.access_token
-                and not request.extensions.get("qca_explicit_auth")
-            ):
+            if not storage and self.credential and not self.pat and not request.extensions.get("qca_explicit_auth"):
                 token = self.credential.get_token()
                 if inspect.isawaitable(token):
                     token = await token
@@ -436,10 +436,10 @@ class AsyncAPIClient(BaseClient):
         if file_fields:
             # Reading local file objects should not block the event loop.
             args = await anyio.to_thread.run_sync(
-                lambda: self._request_args(method, path, options, self.access_token, file_fields)
+                lambda: self._request_args(method, path, options, self.pat, file_fields)
             )
         else:
-            args = self._request_args(method, path, options, self.access_token, None)
+            args = self._request_args(method, path, options, self.pat, None)
         if stream:
             args["headers"]["Accept"] = "text/event-stream"
         request = self._client.build_request(**args)

qca_sdk-0.1.0/src/qca/common/_resumable_streaming.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import random
+import threading
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from time import monotonic
+from typing import Generic, TypeVar
+
+import anyio
+import httpx
+
+from ._exceptions import APIConnectionError, APIStatusError
+from ._streaming import AsyncStream, Stream
+
+T = TypeVar("T")
+
+_INITIAL_BACKOFF = 0.5
+_MAX_BACKOFF = 10.0
+_HEALTHY_RESET_AFTER = 5.0
+_TERMINAL_EVENT_TYPES = frozenset({"session.status_terminated", "session.deleted"})
+
+Retryable = Callable[[httpx.Request, httpx.Response | None], bool]
+
+
+def _is_terminal_event(event: object) -> bool:
+    return getattr(event, "type", None) in _TERMINAL_EVENT_TYPES
+
+
+class ResumableStream(Generic[T], Iterator[T]):
+    def __init__(
+        self,
+        *,
+        open_stream: Callable[[str | None], Stream[T]],
+        retryable: Retryable,
+        last_event_id: str | None,
+    ) -> None:
+        self._open_stream = open_stream
+        self._retryable = retryable
+        self._last_event_id = last_event_id
+        self._backoff = _INITIAL_BACKOFF
+        self._closed = threading.Event()
+        self._stream: Stream[T] | None = None
+        self._iterator = self._iter_events()
+
+    @property
+    def last_event_id(self) -> str | None:
+        return self._last_event_id
+
+    def __next__(self) -> T:
+        return next(self._iterator)
+
+    def _iter_events(self) -> Iterator[T]:
+        while not self._closed.is_set():
+            connected_at: float | None = None
+            connected_for: float | None = None
+            stream: Stream[T] | None = None
+            try:
+                stream = self._open_stream(self._last_event_id)
+                self._stream = stream
+                connected_at = monotonic()
+                if self._closed.is_set():
+                    return
+                for event in stream:
+                    if self._closed.is_set():
+                        return
+                    if stream.last_event_id:
+                        self._last_event_id = stream.last_event_id
+                    terminal = _is_terminal_event(event)
+                    yield event
+                    if terminal:
+                        return
+            except APIConnectionError as exc:
+                if self._closed.is_set():
+                    return
+                if not self._retryable(exc.request, None):
+                    raise
+            except APIStatusError as exc:
+                if self._closed.is_set():
+                    return
+                if not self._retryable(exc.request, exc.response):
+                    raise
+            finally:
+                if connected_at is not None:
+                    connected_for = monotonic() - connected_at
+                if stream is not None:
+                    stream.close()
+                self._stream = None
+
+            if self._closed.is_set():
+                return
+            if connected_for is not None and connected_for >= _HEALTHY_RESET_AFTER:
+                self._backoff = _INITIAL_BACKOFF
+            delay = random.uniform(self._backoff / 2, self._backoff)
+            self._backoff = min(self._backoff * 2, _MAX_BACKOFF)
+            if self._closed.wait(delay):
+                return
+
+    def close(self) -> None:
+        self._closed.set()
+        if self._stream is not None:
+            self._stream.close()
+
+    def __enter__(self) -> ResumableStream[T]:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncResumableStream(Generic[T], AsyncIterator[T]):
+    def __init__(
+        self,
+        *,
+        open_stream: Callable[[str | None], Awaitable[AsyncStream[T]]],
+        retryable: Retryable,
+        last_event_id: str | None,
+    ) -> None:
+        self._open_stream = open_stream
+        self._retryable = retryable
+        self._last_event_id = last_event_id
+        self._backoff = _INITIAL_BACKOFF
+        self._closed = False
+        self._close_event: anyio.Event | None = None
+        self._cancel_scope: anyio.CancelScope | None = None
+        self._stream: AsyncStream[T] | None = None
+        self._iterator = self._iter_events()
+
+    @property
+    def last_event_id(self) -> str | None:
+        return self._last_event_id
+
+    async def __anext__(self) -> T:
+        return await self._iterator.__anext__()
+
+    async def _open_next_stream(self) -> AsyncStream[T] | None:
+        stream: AsyncStream[T] | None = None
+        with anyio.CancelScope() as cancel_scope:
+            self._cancel_scope = cancel_scope
+            if self._closed:
+                cancel_scope.cancel()
+            try:
+                stream = await self._open_stream(self._last_event_id)
+            finally:
+                if self._cancel_scope is cancel_scope:
+                    self._cancel_scope = None
+        return stream
+
+    async def _next_event(self, stream: AsyncStream[T]) -> tuple[bool, T | None]:
+        event: T | None = None
+        exhausted = False
+        with anyio.CancelScope() as cancel_scope:
+            self._cancel_scope = cancel_scope
+            if self._closed:
+                cancel_scope.cancel()
+            try:
+                event = await stream.__anext__()
+            except StopAsyncIteration:
+                exhausted = True
+            finally:
+                if self._cancel_scope is cancel_scope:
+                    self._cancel_scope = None
+        return exhausted, event
+
+    async def _close_stream(self, stream: AsyncStream[T]) -> None:
+        if self._stream is not stream:
+            return
+        self._stream = None
+        await stream.close()
+
+    async def _iter_events(self) -> AsyncIterator[T]:
+        while not self._closed:
+            connected_at: float | None = None
+            connected_for: float | None = None
+            stream: AsyncStream[T] | None = None
+            try:
+                stream = await self._open_next_stream()
+                if stream is None:
+                    return
+                self._stream = stream
+                connected_at = monotonic()
+                if self._closed:
+                    return
+                while not self._closed:
+                    exhausted, event = await self._next_event(stream)
+                    if self._closed:
+                        return
+                    if exhausted:
+                        break
+                    if event is None:
+                        raise RuntimeError("stream read was interrupted without closing")
+                    if stream.last_event_id:
+                        self._last_event_id = stream.last_event_id
+                    terminal = _is_terminal_event(event)
+                    yield event
+                    if terminal:
+                        return
+            except APIConnectionError as exc:
+                if self._closed:
+                    return
+                if not self._retryable(exc.request, None):
+                    raise
+            except APIStatusError as exc:
+                if self._closed:
+                    return
+                if not self._retryable(exc.request, exc.response):
+                    raise
+            finally:
+                if connected_at is not None:
+                    connected_for = monotonic() - connected_at
+                if stream is not None:
+                    with anyio.CancelScope(shield=True):
+                        await self._close_stream(stream)
+
+            if self._closed:
+                return
+            if connected_for is not None and connected_for >= _HEALTHY_RESET_AFTER:
+                self._backoff = _INITIAL_BACKOFF
+            delay = random.uniform(self._backoff / 2, self._backoff)
+            self._backoff = min(self._backoff * 2, _MAX_BACKOFF)
+            close_event = anyio.Event()
+            self._close_event = close_event
+            if self._closed:
+                close_event.set()
+            with anyio.move_on_after(delay):
+                await close_event.wait()
+            self._close_event = None
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._close_event is not None:
+            self._close_event.set()
+        if self._cancel_scope is not None:
+            self._cancel_scope.cancel()
+        if self._stream is not None:
+            with anyio.CancelScope(shield=True):
+                await self._close_stream(self._stream)
+
+    async def __aenter__(self) -> AsyncResumableStream[T]:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()