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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qca-sdk
-Version: 0.0.1.dev4
+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.dev4 → 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.dev4 → 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.dev4 → qca_sdk-0.1.0}/pyproject.toml

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

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

@@ -16,6 +16,7 @@ from qca._version import __version__
 from ._exceptions import APIConnectionError, APIResponseValidationError, APITimeoutError, status_error
 from ._files import multipart_parts
 from ._models import parse_response
+from ._platform import platform_headers
 from ._response import (
     APIResponse,
     AsyncAPIResponse,
@@ -33,6 +34,15 @@ from .pagination import AsyncPage, SyncPage
 DEFAULT_TIMEOUT = httpx.Timeout(60.0, connect=10.0)
 
 
+def _timeout_seconds(timeout: Any) -> int | None:
+    """The deadline the server should expect, in whole seconds like the Go SDK."""
+    if isinstance(timeout, httpx.Timeout):
+        timeout = timeout.read
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        return None
+    return int(timeout)
+
+
 class BaseClient:
     _client: Any
     _default_base_url: str
@@ -44,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,
@@ -54,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:
@@ -70,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,
@@ -88,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):
@@ -110,13 +118,32 @@ 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({"Accept": "application/json", "User-Agent": f"qca-python/{__version__}"})
+        headers = httpx.Headers(
+            {
+                "Accept": "application/json",
+                "User-Agent": f"qca-python/{__version__}",
+                "X-Qoder-Retry-Count": "0",
+                **platform_headers(),
+            }
+        )
         if token:
             headers["Authorization"] = f"Bearer {token}"
         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(
@@ -129,12 +156,17 @@ class BaseClient:
     ) -> dict[str, Any]:
         headers = self._headers(options, token)
         timeout = options.get("timeout", NOT_GIVEN)
+        effective_timeout = self.timeout if isinstance(timeout, NotGiven) else timeout
+        if "X-Qoder-Timeout" not in headers:
+            seconds = _timeout_seconds(effective_timeout)
+            if seconds:
+                headers["X-Qoder-Timeout"] = str(seconds)
         args = dict(
             method=method,
             url=self.base_url.join(path.lstrip("/")),
             headers=headers,
             params=query_pairs({**self.default_query, **options.get("query", {})}),
-            timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
+            timeout=effective_timeout,
         )
         if file_fields:
             args["files"] = multipart_parts(options.get("body", {}), file_fields)
@@ -221,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,
@@ -231,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,
@@ -244,13 +276,11 @@ class SyncAPIClient(BaseClient):
         self._client = http_client or httpx.Client(timeout=timeout, follow_redirects=False)
 
     def _send(self, request: httpx.Request, *, storage: bool = False) -> httpx.Response:
+        track_retries = request.headers.get("X-Qoder-Retry-Count") == "0"
         for attempt in range(self.max_retries + 1):
-            if (
-                not storage
-                and self.credential
-                and not self.access_token
-                and "Authorization" not in self.default_headers
-            ):
+            if track_retries and attempt:
+                request.headers["X-Qoder-Retry-Count"] = str(attempt)
+            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"):
@@ -290,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)
@@ -336,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,
@@ -346,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,
@@ -359,13 +389,11 @@ class AsyncAPIClient(BaseClient):
         self._client = http_client or httpx.AsyncClient(timeout=timeout, follow_redirects=False)
 
     async def _send(self, request: httpx.Request, *, storage: bool = False) -> httpx.Response:
+        track_retries = request.headers.get("X-Qoder-Retry-Count") == "0"
         for attempt in range(self.max_retries + 1):
-            if (
-                not storage
-                and self.credential
-                and not self.access_token
-                and not request.extensions.get("qca_explicit_auth")
-            ):
+            if track_retries and attempt:
+                request.headers["X-Qoder-Retry-Count"] = str(attempt)
+            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
@@ -408,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/_platform.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import platform
+
+from qca._version import __version__
+
+# The spellings match the Go SDK's convention/requestconfig.go on purpose: the
+# server aggregates SDK usage across languages, so the same machine has to land
+# in the same bucket no matter which SDK called. platform.machine() and Go's
+# runtime.GOARCH name the same architecture differently, hence the aliases.
+_OS_NAMES = {
+    "darwin": "MacOS",
+    "windows": "Windows",
+    "linux": "Linux",
+    "ios": "iOS",
+    "android": "Android",
+    "freebsd": "FreeBSD",
+    "openbsd": "OpenBSD",
+}
+
+_ARCH_NAMES = {
+    "386": "x32",
+    "i386": "x32",
+    "i686": "x32",
+    "x86": "x32",
+    "amd64": "x64",
+    "x86_64": "x64",
+    "arm": "arm",
+    "armv7l": "arm",
+    "arm64": "arm64",
+    "aarch64": "arm64",
+}
+
+
+def platform_headers() -> dict[str, str]:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    return {
+        "X-Qoder-Lang": "python",
+        "X-Qoder-Package-Version": __version__,
+        "X-Qoder-OS": _OS_NAMES.get(system, f"Other:{system or 'unknown'}"),
+        "X-Qoder-Arch": _ARCH_NAMES.get(machine, f"other:{machine or 'unknown'}"),
+        "X-Qoder-Runtime": platform.python_implementation(),
+        "X-Qoder-Runtime-Version": platform.python_version(),
+    }