cognicloud 0.9.0__tar.gz

cognicloud-0.9.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: cognicloud
+Version: 0.9.0
+Summary: CogniCloud SDK: browser sessions for agents, and the platform API.
+License: LicenseRef-Proprietary
+Project-URL: Source, https://github.com/Flippico/cognicloud-python-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cognicloud
+
+Use CogniCloud from Python. Version 0.4.0 covers browser sessions for agents; the other products come later. Same behaviour as [`@cognicloud/sdk`](https://github.com/Flippico/cognicloud-js-sdk) and [`cognicloud-sdk`](https://github.com/Flippico/cognicloud-rust-sdk).
+
+## Install
+
+Python 3.10 or newer. No dependencies.
+
+```bash
+pip install "git+https://github.com/Flippico/cognicloud-python-sdk.git"
+```
+
+## Browser sessions
+
+```python
+from cognicloud import CogniCloud
+
+cc = CogniCloud(amadeus_token)
+session = cc.browser.sessions.create(timeout_minutes=15)
+print(session.cdp_url)   # connect Playwright, Puppeteer or any CDP client here
+cc.browser.sessions.stop(session.id)
+```
+
+- `timeout_minutes` is 1 to 240 and defaults to 15.
+- Closing the CDP connection does not stop a session; call `sessions.stop`.
+- `status` is `active` or `stopped`; `cdp_url` and `live_url` are `None` once stopped. `live_url` is a page where a person can watch and take over the browser.
+- `sessions.list()` returns `items` and `concurrency` (`active`, `limit`). A start beyond the limit raises `CogniCloudError` with `status == 429` and `code == "concurrency_limit"`.
+- Proxy countries, profiles, screen sizes, captcha solving and recording are not available yet. `browser.countries()` and `browser.profiles()` return empty lists.
+
+## Call an endpoint
+
+```python
+import os
+from cognicloud import EndpointClient, ResponsesRequest, McpTool, EmbeddingsRequest, DeltaEvent, DoneEvent, ErrorEvent
+
+endpoint = EndpointClient(os.environ["COGNICLOUD_KEY"], endpoint_id=os.environ["COGNICLOUD_ENDPOINT_ID"])
+
+answer = endpoint.responses(
+    ResponsesRequest(
+        input="Is this invoice valid?",
+        instructions="Check invoices.",
+        tools=[McpTool("ksef", allowed_tools=["validate_invoice_xml"])],
+        tool_choice="required",
+    )
+)
+next_answer = endpoint.responses(ResponsesRequest("And this one?", previous_response_id=answer.response_id))
+
+vectors = endpoint.embeddings(EmbeddingsRequest(["first text", "second text"], dimensions=256))
+```
+
+`McpTool` names an MCP server with `server_url` and `bearer_token`. The gateway checks the address (https, with no credentials or fragment) and passes both to the provider. A tool with only `server_label` names a server the gateway is configured with. The answer's `response_id` continues the conversation on the same endpoint, and `output_items` holds the tool calls. `embeddings` needs an endpoint whose deployment is an embedding model, and returns one vector per input.
+
+## Streaming
+
+```python
+for event in endpoint.stream({"messages": [{"role": "user", "content": "Write a haiku."}]}):
+    if isinstance(event, DeltaEvent):
+        print(event.text, end="")
+    elif isinstance(event, DoneEvent):
+        print(f"\n{event.answer.usage.total_tokens} tokens")
+    elif isinstance(event, ErrorEvent):
+        print(f"{event.code}: {event.message}")
+```
+
+`ResponsesRequest(extra={...})` sends any other field to the provider unchanged, such as `seed` or `reasoning`. The gateway refuses the fields it sets itself, such as `n` or `store`.
+
+`stream` opens the call before it returns, so a refusal raises immediately, before any event. Each event is a `DeltaEvent` (`text`), then one `DoneEvent` (`answer`), or one `ErrorEvent` (`code`, `message`). Streams are not retried and have no total timeout; the gateway ends them at five minutes. Stop early by closing the iterator; the gateway still settles the call.
+
+## Errors
+
+Every failed request raises `CogniCloudError` with `status` (the HTTP status, `0` when no answer came back), `code` (CogniCloud's stable error code, or a local one such as `timeout` or `network_error`) and `message`.
+
+## Configuration
+
+| Option | Default | |
+| --- | --- | --- |
+| `token` | required | The signed-in person's Amadeus session token. |
+| `tenant` | `"cognicloud"` | The workspace, sent as `tenant_id`. The platform workspace is open to every signed-in user. |
+| `locale` | `"en"` | `Accept-Language` for localised responses. |
+| `timeout` | `30.0` | Seconds per request. |
+| `max_retries` | `2` | For `429` and `5xx`, on reads only. Starts and stops are never retried. |
+| `browser_base_url` | `https://cognicloud.flippi.co/api/v1/browser` | Point at another environment. |
+
+## Development
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+The tests run against a local HTTP stub and need no network access.
+
+See [CHANGELOG.md](./CHANGELOG.md).

cognicloud-0.9.0/README.md

@@ -0,0 +1,92 @@
+# cognicloud
+
+Use CogniCloud from Python. Version 0.4.0 covers browser sessions for agents; the other products come later. Same behaviour as [`@cognicloud/sdk`](https://github.com/Flippico/cognicloud-js-sdk) and [`cognicloud-sdk`](https://github.com/Flippico/cognicloud-rust-sdk).
+
+## Install
+
+Python 3.10 or newer. No dependencies.
+
+```bash
+pip install "git+https://github.com/Flippico/cognicloud-python-sdk.git"
+```
+
+## Browser sessions
+
+```python
+from cognicloud import CogniCloud
+
+cc = CogniCloud(amadeus_token)
+session = cc.browser.sessions.create(timeout_minutes=15)
+print(session.cdp_url)   # connect Playwright, Puppeteer or any CDP client here
+cc.browser.sessions.stop(session.id)
+```
+
+- `timeout_minutes` is 1 to 240 and defaults to 15.
+- Closing the CDP connection does not stop a session; call `sessions.stop`.
+- `status` is `active` or `stopped`; `cdp_url` and `live_url` are `None` once stopped. `live_url` is a page where a person can watch and take over the browser.
+- `sessions.list()` returns `items` and `concurrency` (`active`, `limit`). A start beyond the limit raises `CogniCloudError` with `status == 429` and `code == "concurrency_limit"`.
+- Proxy countries, profiles, screen sizes, captcha solving and recording are not available yet. `browser.countries()` and `browser.profiles()` return empty lists.
+
+## Call an endpoint
+
+```python
+import os
+from cognicloud import EndpointClient, ResponsesRequest, McpTool, EmbeddingsRequest, DeltaEvent, DoneEvent, ErrorEvent
+
+endpoint = EndpointClient(os.environ["COGNICLOUD_KEY"], endpoint_id=os.environ["COGNICLOUD_ENDPOINT_ID"])
+
+answer = endpoint.responses(
+    ResponsesRequest(
+        input="Is this invoice valid?",
+        instructions="Check invoices.",
+        tools=[McpTool("ksef", allowed_tools=["validate_invoice_xml"])],
+        tool_choice="required",
+    )
+)
+next_answer = endpoint.responses(ResponsesRequest("And this one?", previous_response_id=answer.response_id))
+
+vectors = endpoint.embeddings(EmbeddingsRequest(["first text", "second text"], dimensions=256))
+```
+
+`McpTool` names an MCP server with `server_url` and `bearer_token`. The gateway checks the address (https, with no credentials or fragment) and passes both to the provider. A tool with only `server_label` names a server the gateway is configured with. The answer's `response_id` continues the conversation on the same endpoint, and `output_items` holds the tool calls. `embeddings` needs an endpoint whose deployment is an embedding model, and returns one vector per input.
+
+## Streaming
+
+```python
+for event in endpoint.stream({"messages": [{"role": "user", "content": "Write a haiku."}]}):
+    if isinstance(event, DeltaEvent):
+        print(event.text, end="")
+    elif isinstance(event, DoneEvent):
+        print(f"\n{event.answer.usage.total_tokens} tokens")
+    elif isinstance(event, ErrorEvent):
+        print(f"{event.code}: {event.message}")
+```
+
+`ResponsesRequest(extra={...})` sends any other field to the provider unchanged, such as `seed` or `reasoning`. The gateway refuses the fields it sets itself, such as `n` or `store`.
+
+`stream` opens the call before it returns, so a refusal raises immediately, before any event. Each event is a `DeltaEvent` (`text`), then one `DoneEvent` (`answer`), or one `ErrorEvent` (`code`, `message`). Streams are not retried and have no total timeout; the gateway ends them at five minutes. Stop early by closing the iterator; the gateway still settles the call.
+
+## Errors
+
+Every failed request raises `CogniCloudError` with `status` (the HTTP status, `0` when no answer came back), `code` (CogniCloud's stable error code, or a local one such as `timeout` or `network_error`) and `message`.
+
+## Configuration
+
+| Option | Default | |
+| --- | --- | --- |
+| `token` | required | The signed-in person's Amadeus session token. |
+| `tenant` | `"cognicloud"` | The workspace, sent as `tenant_id`. The platform workspace is open to every signed-in user. |
+| `locale` | `"en"` | `Accept-Language` for localised responses. |
+| `timeout` | `30.0` | Seconds per request. |
+| `max_retries` | `2` | For `429` and `5xx`, on reads only. Starts and stops are never retried. |
+| `browser_base_url` | `https://cognicloud.flippi.co/api/v1/browser` | Point at another environment. |
+
+## Development
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+The tests run against a local HTTP stub and need no network access.
+
+See [CHANGELOG.md](./CHANGELOG.md).

cognicloud-0.9.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cognicloud"
+version = "0.9.0"
+description = "CogniCloud SDK: browser sessions for agents, and the platform API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "LicenseRef-Proprietary" }
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/Flippico/cognicloud-python-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cognicloud-0.9.0/setup.cfg

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

cognicloud-0.9.0/src/cognicloud/__init__.py

@@ -0,0 +1,52 @@
+"""CogniCloud SDK for Python. Standard library only; needs Python 3.10 or newer."""
+
+from .browser import (
+    BrowserApi,
+    BrowserConcurrency,
+    BrowserProfile,
+    BrowserSession,
+    BrowserSessionList,
+    BrowserSessionsApi,
+    ProxyCountry,
+)
+from .client import CogniCloud
+from .endpoint import (
+    DeltaEvent,
+    DoneEvent,
+    Embedding,
+    EmbeddingsRequest,
+    EmbeddingsResult,
+    EndpointClient,
+    ErrorEvent,
+    McpTool,
+    ResponseResult,
+    ResponsesRequest,
+    StreamEvent,
+    Usage,
+)
+from .errors import CogniCloudError
+
+__all__ = [
+    "BrowserApi",
+    "BrowserConcurrency",
+    "BrowserProfile",
+    "BrowserSession",
+    "BrowserSessionList",
+    "BrowserSessionsApi",
+    "CogniCloud",
+    "CogniCloudError",
+    "DeltaEvent",
+    "DoneEvent",
+    "Embedding",
+    "EmbeddingsRequest",
+    "EmbeddingsResult",
+    "EndpointClient",
+    "ErrorEvent",
+    "McpTool",
+    "ProxyCountry",
+    "ResponseResult",
+    "ResponsesRequest",
+    "StreamEvent",
+    "Usage",
+]
+__version__ = "0.9.0"

cognicloud-0.9.0/src/cognicloud/_http.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import json
+import socket
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .errors import CogniCloudError
+
+RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
+
+
+@dataclass(frozen=True)
+class HttpConfig:
+    base_url: str
+    locale: str
+    timeout: float
+    max_retries: int
+
+
+def request(
+    config: HttpConfig,
+    method: str,
+    path: str,
+    headers: dict[str, str],
+    body: Optional[Any] = None,
+    retry: bool = True,
+) -> Any:
+    """Sends one request and returns the decoded JSON body (None for 204). Retries 429 and 5xx only when `retry` is set."""
+    url = config.base_url.rstrip("/") + path
+    retries = config.max_retries if retry else 0
+    payload = None if body is None else json.dumps(body).encode("utf-8")
+    all_headers = {"accept": "application/json", "accept-language": config.locale, **headers}
+    if payload is not None:
+        all_headers["content-type"] = "application/json"
+
+    attempt = 0
+    while True:
+        http_request = urllib.request.Request(url, data=payload, method=method, headers=all_headers)
+        try:
+            with urllib.request.urlopen(http_request, timeout=config.timeout) as response:
+                raw = response.read()
+                return None if response.status == 204 or not raw else json.loads(raw)
+        except urllib.error.HTTPError as error:
+            if error.code in RETRYABLE_STATUSES and attempt < retries:
+                time.sleep(0.25 * 2**attempt)
+                attempt += 1
+                continue
+            raise _api_error(error.code, error.read()) from None
+        except (TimeoutError, socket.timeout):
+            if attempt < retries:
+                time.sleep(0.25 * 2**attempt)
+                attempt += 1
+                continue
+            raise CogniCloudError(0, "timeout", "The request timed out.") from None
+        except urllib.error.URLError as error:
+            timed_out = isinstance(error.reason, (TimeoutError, socket.timeout))
+            if attempt < retries:
+                time.sleep(0.25 * 2**attempt)
+                attempt += 1
+                continue
+            if timed_out:
+                raise CogniCloudError(0, "timeout", "The request timed out.") from None
+            raise CogniCloudError(0, "network_error", "The request could not reach CogniCloud.") from None
+
+
+def _api_error(status: int, raw: bytes) -> CogniCloudError:
+    try:
+        body = json.loads(raw) if raw else {}
+    except ValueError:
+        body = {}
+    code = body.get("error") if isinstance(body.get("error"), str) else "http_error"
+    message = body.get("message") if isinstance(body.get("message"), str) else "The request failed."
+    return CogniCloudError(status, code, message)
+
+
+def open_stream(
+    config: HttpConfig,
+    method: str,
+    path: str,
+    headers: dict[str, str],
+    body: Optional[Any] = None,
+) -> Any:
+    """Opens a streamed call and returns the response to read as it arrives. Never retried, and the timeout bounds each
+    read rather than the whole stream, because a stream may run for minutes."""
+    url = config.base_url.rstrip("/") + path
+    payload = None if body is None else json.dumps(body).encode("utf-8")
+    all_headers = {"accept": "text/event-stream", "accept-language": config.locale, **headers}
+    if payload is not None:
+        all_headers["content-type"] = "application/json"
+    http_request = urllib.request.Request(url, data=payload, method=method, headers=all_headers)
+    try:
+        return urllib.request.urlopen(http_request, timeout=config.timeout)
+    except urllib.error.HTTPError as error:
+        raise _api_error(error.code, error.read()) from None
+    except (TimeoutError, socket.timeout):
+        raise CogniCloudError(0, "timeout", "The request timed out.") from None
+    except urllib.error.URLError as error:
+        if isinstance(error.reason, (TimeoutError, socket.timeout)):
+            raise CogniCloudError(0, "timeout", "The request timed out.") from None
+        raise CogniCloudError(0, "network_error", "The request could not reach CogniCloud.") from None

cognicloud-0.9.0/src/cognicloud/_sse.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Record:
+    event: str
+    data: str
+
+
+def records(lines: Iterable[bytes]) -> Iterator[Record]:
+    """Splits Server-Sent Events into records. Lines may end in LF or CRLF; a record ends at a blank line, and its
+    `data:` lines are joined with newlines. A record without an `event:` line is named `message`."""
+    event: Optional[str] = None
+    data: list[str] = []
+    for raw in lines:
+        line = raw.decode("utf-8").rstrip("\r\n")
+        if line == "":
+            if event is not None or data:
+                yield Record(event or "message", "\n".join(data))
+                event = None
+                data = []
+        elif line.startswith("event:"):
+            event = _value(line[len("event:") :])
+        elif line.startswith("data:"):
+            data.append(_value(line[len("data:") :]))
+
+
+def _value(text: str) -> str:
+    return text[1:] if text.startswith(" ") else text

cognicloud-0.9.0/src/cognicloud/browser.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import quote
+
+from ._http import HttpConfig, request
+
+
+@dataclass(frozen=True)
+class BrowserSession:
+    """A session is `active` until it stops; then `cdp_url` and `live_url` are None."""
+
+    id: str
+    status: str
+    cdp_url: Optional[str]
+    live_url: Optional[str]
+    profile_id: Optional[str]
+    proxy_country_code: Optional[str]
+    solve_captchas: bool
+    recording: bool
+    screen: Optional[dict[str, int]]
+    timeout_at: str
+    started_at: str
+    finished_at: Optional[str]
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "BrowserSession":
+        return cls(
+            id=data["id"],
+            status=data["status"],
+            cdp_url=data.get("cdpUrl"),
+            live_url=data.get("liveUrl"),
+            profile_id=data.get("profileId"),
+            proxy_country_code=data.get("proxyCountryCode"),
+            solve_captchas=bool(data.get("solveCaptchas")),
+            recording=bool(data.get("recording")),
+            screen=data.get("screen"),
+            timeout_at=data["timeoutAt"],
+            started_at=data["startedAt"],
+            finished_at=data.get("finishedAt"),
+        )
+
+
+@dataclass(frozen=True)
+class BrowserConcurrency:
+    active: int
+    limit: int
+
+
+@dataclass(frozen=True)
+class BrowserSessionList:
+    items: list[BrowserSession]
+    concurrency: BrowserConcurrency
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "BrowserSessionList":
+        concurrency = data["concurrency"]
+        return cls(
+            items=[BrowserSession.from_json(item) for item in data["items"]],
+            concurrency=BrowserConcurrency(active=concurrency["active"], limit=concurrency["limit"]),
+        )
+
+
+@dataclass(frozen=True)
+class ProxyCountry:
+    code: str
+    name: str
+
+
+@dataclass(frozen=True)
+class BrowserProfile:
+    id: str
+    name: str
+    cookie_domains: list[str]
+    last_used_at: Optional[str]
+    created_at: str
+
+
+class BrowserSessionsApi:
+    """Starts, lists, reads and stops browser sessions."""
+
+    def __init__(self, config: HttpConfig, headers: dict[str, str]) -> None:
+        self._config = config
+        self._headers = headers
+
+    def create(self, timeout_minutes: Optional[int] = None) -> BrowserSession:
+        """Starts a session. Its `cdp_url` and `live_url` carry the session token; treat them as secrets.
+
+        `timeout_minutes` is 1 to 240 and defaults to 15. A start beyond the workspace's limit raises
+        CogniCloudError with status 429 and code `concurrency_limit`.
+        """
+        body: dict[str, Any] = {}
+        if timeout_minutes is not None:
+            body["timeoutMinutes"] = timeout_minutes
+        data = request(self._config, "POST", "/sessions", self._headers, body, retry=False)
+        return BrowserSession.from_json(data)
+
+    def list(self) -> BrowserSessionList:
+        """The workspace's sessions, newest first, with concurrency."""
+        return BrowserSessionList.from_json(request(self._config, "GET", "/sessions", self._headers))
+
+    def get(self, session_id: str) -> BrowserSession:
+        return BrowserSession.from_json(
+            request(self._config, "GET", f"/sessions/{quote(session_id, safe='')}", self._headers)
+        )
+
+    def stop(self, session_id: str) -> BrowserSession:
+        """Closing the CDP connection does not stop a session; this does."""
+        data = request(
+            self._config, "POST", f"/sessions/{quote(session_id, safe='')}/stop", self._headers, retry=False
+        )
+        return BrowserSession.from_json(data)
+
+
+class BrowserApi:
+    """Manages the browser product with the signed-in person's session."""
+
+    def __init__(self, config: HttpConfig, headers: dict[str, str]) -> None:
+        self._config = config
+        self._headers = headers
+        self.sessions = BrowserSessionsApi(config, headers)
+
+    def countries(self) -> list[ProxyCountry]:
+        """Proxy countries a session can route through. Empty until proxies are available."""
+        data = request(self._config, "GET", "/countries", self._headers)
+        return [ProxyCountry(code=item["code"], name=item["name"]) for item in data]
+
+    def profiles(self) -> list[BrowserProfile]:
+        """Profiles keep cookies between sessions. Empty until profiles are available."""
+        data = request(self._config, "GET", "/profiles", self._headers)
+        return [
+            BrowserProfile(
+                id=item["id"],
+                name=item["name"],
+                cookie_domains=item["cookieDomains"],
+                last_used_at=item.get("lastUsedAt"),
+                created_at=item["createdAt"],
+            )
+            for item in data
+        ]

cognicloud-0.9.0/src/cognicloud/client.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._http import HttpConfig
+from .browser import BrowserApi
+
+DEFAULT_TENANT = "cognicloud"
+DEFAULT_BROWSER_BASE_URL = "https://cognicloud.flippi.co/api/v1/browser"
+
+
+class CogniCloud:
+    """Manage CogniCloud resources with the signed-in person's session.
+
+    `token` is the Amadeus session token, sent as `Authorization: Bearer`. `tenant` is the workspace, sent as the
+    `tenant_id` header; it defaults to the platform workspace, which every signed-in user may use.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        tenant: str = DEFAULT_TENANT,
+        locale: str = "en",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        browser_base_url: str = DEFAULT_BROWSER_BASE_URL,
+    ) -> None:
+        config = HttpConfig(base_url=browser_base_url, locale=locale, timeout=timeout, max_retries=max_retries)
+        headers = {"authorization": f"Bearer {token}", "tenant_id": tenant}
+        self.browser = BrowserApi(config, headers)

cognicloud-0.9.0/src/cognicloud/endpoint.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import json
+import socket
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional, Union
+from urllib.parse import quote
+
+from ._http import HttpConfig, open_stream, request
+from ._sse import Record, records
+from .errors import CogniCloudError
+
+DEFAULT_TENANT = "cognicloud"
+DEFAULT_GATEWAY_BASE_URL = "https://cognicloud.flippi.co/api/v1/ai-gateway"
+
+
+@dataclass(frozen=True)
+class McpTool:
+    """An MCP server a Responses call may use.
+
+    Name the server with `server_url` and its bearer token with `bearer_token`. The gateway checks the address (https,
+    no credentials or fragment), sets approval to `never`, and passes both to the provider. A tool with only
+    `server_label` names a server the gateway is configured with.
+    """
+
+    server_label: str
+    allowed_tools: Optional[list[str]] = None
+    server_url: Optional[str] = None
+    bearer_token: Optional[str] = field(default=None, repr=False)
+
+    def to_json(self) -> dict[str, Any]:
+        body: dict[str, Any] = {"type": "mcp", "server_label": self.server_label}
+        if self.server_url is not None:
+            body["server_url"] = self.server_url
+        if self.bearer_token is not None:
+            body["headers"] = {"Authorization": f"Bearer {self.bearer_token}"}
+        if self.allowed_tools is not None:
+            body["allowed_tools"] = self.allowed_tools
+        return body
+
+
+@dataclass(frozen=True)
+class ResponsesRequest:
+    """A Responses call with optional MCP tools, instructions and chaining. `input` is text or role/content messages."""
+
+    input: Union[str, list[dict[str, Any]]]
+    instructions: Optional[str] = None
+    previous_response_id: Optional[str] = None
+    tools: list[McpTool] = field(default_factory=list)
+    tool_choice: Optional[Literal["auto", "required", "none"]] = None
+    max_output_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    top_p: Optional[float] = None
+    # Any other field, sent to the provider unchanged. The gateway refuses the fields it sets itself, such as `n`.
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> dict[str, Any]:
+        body: dict[str, Any] = {**self.extra, "input": self.input}
+        optional = {
+            "instructions": self.instructions,
+            "previous_response_id": self.previous_response_id,
+            "tool_choice": self.tool_choice,
+            "max_output_tokens": self.max_output_tokens,
+            "temperature": self.temperature,
+            "top_p": self.top_p,
+        }
+        body.update({key: value for key, value in optional.items() if value is not None})
+        if self.tools:
+            body["tools"] = [tool.to_json() for tool in self.tools]
+        return body
+
+
+@dataclass(frozen=True)
+class EmbeddingsRequest:
+    """Text to embed: one string or up to 256. The endpoint's embedding deployment is the model."""
+
+    input: Union[str, list[str]]
+    dimensions: Optional[int] = None
+
+    def to_json(self) -> dict[str, Any]:
+        body: dict[str, Any] = {"input": self.input}
+        if self.dimensions is not None:
+            body["dimensions"] = self.dimensions
+        return body
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "Usage":
+        return cls(data["inputTokens"], data["outputTokens"], data["totalTokens"])
+
+
+@dataclass(frozen=True)
+class ResponseResult:
+    """An answer. `response_id` and `output_items` are set only for Responses calls."""
+
+    id: str
+    model: str
+    output: str
+    finish_reason: Optional[str]
+    usage: Usage
+    response_id: Optional[str] = None
+    output_items: Optional[list[Any]] = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "ResponseResult":
+        return cls(
+            id=data["id"],
+            model=data["model"],
+            output=data["output"],
+            finish_reason=data.get("finishReason"),
+            usage=Usage.from_json(data["usage"]),
+            response_id=data.get("responseId"),
+            output_items=data.get("outputItems"),
+        )
+
+
+@dataclass(frozen=True)
+class Embedding:
+    index: int
+    embedding: list[float]
+
+
+@dataclass(frozen=True)
+class EmbeddingsResult:
+    """One item per input, in input order."""
+
+    id: str
+    model: str
+    data: list[Embedding]
+    usage: Usage
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "EmbeddingsResult":
+        return cls(
+            id=data["id"],
+            model=data["model"],
+            data=[Embedding(item["index"], item["embedding"]) for item in data["data"]],
+            usage=Usage.from_json(data["usage"]),
+        )
+
+
+@dataclass(frozen=True)
+class DeltaEvent:
+    """Text as it is generated."""
+
+    text: str
+
+
+@dataclass(frozen=True)
+class DoneEvent:
+    """The complete answer. It is always the last event of a successful stream."""
+
+    answer: ResponseResult
+
+
+@dataclass(frozen=True)
+class ErrorEvent:
+    """A failure, instead of `DoneEvent`. The stream ends after it."""
+
+    code: str
+    message: str
+
+
+StreamEvent = Union[DeltaEvent, DoneEvent, ErrorEvent]
+
+
+def encode_tenant(tenant: str) -> str:
+    """How an invoke URL names its tenant: the tenant's name as UTF-8, in lowercase hex."""
+    return tenant.encode("utf-8").hex()
+
+
+class EndpointClient:
+    """Calls one AI Gateway endpoint with its own credential.
+
+    Pass the endpoint's invoke URL as `url` (as CogniCloud issued it), or the `endpoint_id` and `tenant`. Invoke calls
+    are never retried, because a retried call can be billed twice.
+    """
+
+    def __init__(
+        self,
+        credential: str,
+        *,
+        endpoint_id: Optional[str] = None,
+        url: Optional[str] = None,
+        tenant: str = DEFAULT_TENANT,
+        base_url: str = DEFAULT_GATEWAY_BASE_URL,
+        locale: str = "en",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        if (endpoint_id is None) == (url is None):
+            raise ValueError("Pass exactly one of endpoint_id or url.")
+        if url is None:
+            url = f"{base_url.rstrip('/')}/invoke/{encode_tenant(tenant)}/{quote(endpoint_id or '', safe='')}"
+        self.url = url
+        self._config = HttpConfig(base_url=url, locale=locale, timeout=timeout, max_retries=max_retries)
+        self._headers = {"authorization": f"Bearer {credential}"}
+
+    def invoke(self, body: Mapping[str, Any]) -> ResponseResult:
+        """Sends the body through the endpoint's request mapping and returns the answer in one shape. Without a mapping
+        the body goes to the provider as it is, with no streaming. Use `stream` to stream."""
+        data = request(self._config, "POST", "", self._headers, dict(body), retry=False)
+        return ResponseResult.from_json(data)
+
+    def responses(self, request_body: ResponsesRequest) -> ResponseResult:
+        """A Responses call with optional MCP tools, instructions and chaining. Never retried."""
+        data = request(self._config, "POST", "", self._headers, request_body.to_json(), retry=False)
+        return ResponseResult.from_json(data)
+
+    def embeddings(self, request_body: EmbeddingsRequest) -> EmbeddingsResult:
+        """Embeds text through the endpoint's embedding deployment. Billed as prompt tokens. Never retried."""
+        data = request(self._config, "POST", "/embeddings", self._headers, request_body.to_json(), retry=False)
+        return EmbeddingsResult.from_json(data)
+
+    def stream(self, body: Union[Mapping[str, Any], ResponsesRequest]) -> Iterator[StreamEvent]:
+        """Streams a chat or Responses call: sets `stream: true` and yields events as they arrive.
+
+        The call is opened before this returns, so a refusal raises here, before any event. Stop early by closing the
+        iterator; the gateway still settles the call.
+        """
+        payload = dict(body.to_json() if isinstance(body, ResponsesRequest) else body)
+        payload["stream"] = True
+        response = open_stream(self._config, "POST", "", self._headers, payload)
+        return _events(response)
+
+    def stream_responses(self, request_body: ResponsesRequest) -> Iterator[StreamEvent]:
+        """Streams a Responses call, for tools or chaining. See `stream`."""
+        return self.stream(request_body)
+
+
+def _events(response: Any) -> Iterator[StreamEvent]:
+    try:
+        for record in records(response):
+            event = _decode(record)
+            if event is None:
+                continue
+            yield event
+            if not isinstance(event, DeltaEvent):
+                return
+        yield ErrorEvent("stream_ended", "The stream ended before its final event.")
+    except (TimeoutError, socket.timeout):
+        raise CogniCloudError(0, "timeout", "The stream timed out.") from None
+    except OSError:
+        raise CogniCloudError(0, "network_error", "The stream was interrupted.") from None
+    finally:
+        response.close()
+
+
+def _decode(record: Record) -> Optional[StreamEvent]:
+    """Events the gateway does not send are ignored, so a newer gateway can add events without breaking this client."""
+    if record.event == "delta":
+        return DeltaEvent(json.loads(record.data)["text"])
+    if record.event == "done":
+        return DoneEvent(ResponseResult.from_json(json.loads(record.data)))
+    if record.event == "error":
+        error = json.loads(record.data)
+        return ErrorEvent(error["code"], error["message"])
+    return None

cognicloud-0.9.0/src/cognicloud/errors.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+class CogniCloudError(Exception):
+    """A failed request. `status` is the HTTP status (0 when no answer came back); `code` is CogniCloud's error code."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message

cognicloud-0.9.0/src/cognicloud.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: cognicloud
+Version: 0.9.0
+Summary: CogniCloud SDK: browser sessions for agents, and the platform API.
+License: LicenseRef-Proprietary
+Project-URL: Source, https://github.com/Flippico/cognicloud-python-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cognicloud
+
+Use CogniCloud from Python. Version 0.4.0 covers browser sessions for agents; the other products come later. Same behaviour as [`@cognicloud/sdk`](https://github.com/Flippico/cognicloud-js-sdk) and [`cognicloud-sdk`](https://github.com/Flippico/cognicloud-rust-sdk).
+
+## Install
+
+Python 3.10 or newer. No dependencies.
+
+```bash
+pip install "git+https://github.com/Flippico/cognicloud-python-sdk.git"
+```
+
+## Browser sessions
+
+```python
+from cognicloud import CogniCloud
+
+cc = CogniCloud(amadeus_token)
+session = cc.browser.sessions.create(timeout_minutes=15)
+print(session.cdp_url)   # connect Playwright, Puppeteer or any CDP client here
+cc.browser.sessions.stop(session.id)
+```
+
+- `timeout_minutes` is 1 to 240 and defaults to 15.
+- Closing the CDP connection does not stop a session; call `sessions.stop`.
+- `status` is `active` or `stopped`; `cdp_url` and `live_url` are `None` once stopped. `live_url` is a page where a person can watch and take over the browser.
+- `sessions.list()` returns `items` and `concurrency` (`active`, `limit`). A start beyond the limit raises `CogniCloudError` with `status == 429` and `code == "concurrency_limit"`.
+- Proxy countries, profiles, screen sizes, captcha solving and recording are not available yet. `browser.countries()` and `browser.profiles()` return empty lists.
+
+## Call an endpoint
+
+```python
+import os
+from cognicloud import EndpointClient, ResponsesRequest, McpTool, EmbeddingsRequest, DeltaEvent, DoneEvent, ErrorEvent
+
+endpoint = EndpointClient(os.environ["COGNICLOUD_KEY"], endpoint_id=os.environ["COGNICLOUD_ENDPOINT_ID"])
+
+answer = endpoint.responses(
+    ResponsesRequest(
+        input="Is this invoice valid?",
+        instructions="Check invoices.",
+        tools=[McpTool("ksef", allowed_tools=["validate_invoice_xml"])],
+        tool_choice="required",
+    )
+)
+next_answer = endpoint.responses(ResponsesRequest("And this one?", previous_response_id=answer.response_id))
+
+vectors = endpoint.embeddings(EmbeddingsRequest(["first text", "second text"], dimensions=256))
+```
+
+`McpTool` names an MCP server with `server_url` and `bearer_token`. The gateway checks the address (https, with no credentials or fragment) and passes both to the provider. A tool with only `server_label` names a server the gateway is configured with. The answer's `response_id` continues the conversation on the same endpoint, and `output_items` holds the tool calls. `embeddings` needs an endpoint whose deployment is an embedding model, and returns one vector per input.
+
+## Streaming
+
+```python
+for event in endpoint.stream({"messages": [{"role": "user", "content": "Write a haiku."}]}):
+    if isinstance(event, DeltaEvent):
+        print(event.text, end="")
+    elif isinstance(event, DoneEvent):
+        print(f"\n{event.answer.usage.total_tokens} tokens")
+    elif isinstance(event, ErrorEvent):
+        print(f"{event.code}: {event.message}")
+```
+
+`ResponsesRequest(extra={...})` sends any other field to the provider unchanged, such as `seed` or `reasoning`. The gateway refuses the fields it sets itself, such as `n` or `store`.
+
+`stream` opens the call before it returns, so a refusal raises immediately, before any event. Each event is a `DeltaEvent` (`text`), then one `DoneEvent` (`answer`), or one `ErrorEvent` (`code`, `message`). Streams are not retried and have no total timeout; the gateway ends them at five minutes. Stop early by closing the iterator; the gateway still settles the call.
+
+## Errors
+
+Every failed request raises `CogniCloudError` with `status` (the HTTP status, `0` when no answer came back), `code` (CogniCloud's stable error code, or a local one such as `timeout` or `network_error`) and `message`.
+
+## Configuration
+
+| Option | Default | |
+| --- | --- | --- |
+| `token` | required | The signed-in person's Amadeus session token. |
+| `tenant` | `"cognicloud"` | The workspace, sent as `tenant_id`. The platform workspace is open to every signed-in user. |
+| `locale` | `"en"` | `Accept-Language` for localised responses. |
+| `timeout` | `30.0` | Seconds per request. |
+| `max_retries` | `2` | For `429` and `5xx`, on reads only. Starts and stops are never retried. |
+| `browser_base_url` | `https://cognicloud.flippi.co/api/v1/browser` | Point at another environment. |
+
+## Development
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+The tests run against a local HTTP stub and need no network access.
+
+See [CHANGELOG.md](./CHANGELOG.md).

cognicloud-0.9.0/src/cognicloud.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/cognicloud/__init__.py
+src/cognicloud/_http.py
+src/cognicloud/_sse.py
+src/cognicloud/browser.py
+src/cognicloud/client.py
+src/cognicloud/endpoint.py
+src/cognicloud/errors.py
+src/cognicloud.egg-info/PKG-INFO
+src/cognicloud.egg-info/SOURCES.txt
+src/cognicloud.egg-info/dependency_links.txt
+src/cognicloud.egg-info/top_level.txt
+tests/test_browser.py
+tests/test_endpoint.py

cognicloud-0.9.0/src/cognicloud.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cognicloud-0.9.0/src/cognicloud.egg-info/top_level.txt

@@ -0,0 +1 @@
+cognicloud

cognicloud-0.9.0/tests/test_browser.py

@@ -0,0 +1,137 @@
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from cognicloud import CogniCloud, CogniCloudError
+
+SESSION = {
+    "id": "b903c5d0",
+    "status": "active",
+    "cdpUrl": "wss://cognicloud.flippi.co/api/v1/browser/sessions/b903c5d0/cdp?token=t",
+    "liveUrl": "https://cognicloud.flippi.co/api/v1/browser/sessions/b903c5d0/live?token=t",
+    "profileId": None,
+    "proxyCountryCode": None,
+    "solveCaptchas": False,
+    "recording": False,
+    "screen": None,
+    "timeoutAt": "2026-10-22T10:15:00Z",
+    "startedAt": "2026-10-22T10:00:00Z",
+    "finishedAt": None,
+}
+
+
+class Stub(BaseHTTPRequestHandler):
+    """Answers from `routes[(method, path)]` as (status, body) and records every request."""
+
+    routes: dict = {}
+    seen: list = []
+
+    def _answer(self):
+        length = int(self.headers.get("content-length", 0))
+        body = self.rfile.read(length) if length else b""
+        Stub.seen.append(
+            {
+                "method": self.command,
+                "path": self.path,
+                "headers": {key.lower(): value for key, value in self.headers.items()},
+                "body": json.loads(body) if body else None,
+            }
+        )
+        status, payload = Stub.routes.get((self.command, self.path.split("?")[0]), (404, {"error": "not_found", "message": "No route matches this path."}))
+        raw = b"" if payload is None else json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    do_GET = _answer
+    do_POST = _answer
+    do_DELETE = _answer
+
+    def log_message(self, *args):
+        pass
+
+
+class BrowserTests(unittest.TestCase):
+    def setUp(self):
+        Stub.routes = {}
+        Stub.seen = []
+        self.server = HTTPServer(("127.0.0.1", 0), Stub)
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.base = f"http://127.0.0.1:{self.server.server_address[1]}/v1/browser"
+
+    def tearDown(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+    def client(self, **options):
+        return CogniCloud("amadeus-token", tenant="acme", browser_base_url=self.base, **options)
+
+    def test_creates_a_session_at_the_browser_base_with_the_session_headers(self):
+        Stub.routes[("POST", "/v1/browser/sessions")] = (201, SESSION)
+        session = self.client().browser.sessions.create(timeout_minutes=15)
+        self.assertEqual(session.id, "b903c5d0")
+        self.assertEqual(session.status, "active")
+        self.assertTrue(session.cdp_url.startswith("wss://"))
+        request = Stub.seen[0]
+        self.assertEqual(request["body"], {"timeoutMinutes": 15})
+        self.assertEqual(request["headers"]["authorization"], "Bearer amadeus-token")
+        self.assertEqual(request["headers"]["tenant_id"], "acme")
+
+    def test_lists_reads_and_stops_sessions(self):
+        stopped = dict(SESSION, status="stopped", cdpUrl=None, liveUrl=None, finishedAt="2026-10-22T10:05:00Z")
+        Stub.routes[("GET", "/v1/browser/sessions")] = (200, {"items": [SESSION], "concurrency": {"active": 1, "limit": 2}})
+        Stub.routes[("GET", "/v1/browser/sessions/b903c5d0")] = (200, SESSION)
+        Stub.routes[("POST", "/v1/browser/sessions/b903c5d0/stop")] = (200, stopped)
+        browser = self.client().browser
+        listed = browser.sessions.list()
+        self.assertEqual((listed.concurrency.active, listed.concurrency.limit), (1, 2))
+        self.assertEqual(browser.sessions.get("b903c5d0").status, "active")
+        after = browser.sessions.stop("b903c5d0")
+        self.assertEqual(after.status, "stopped")
+        self.assertIsNone(after.cdp_url)
+        self.assertEqual(Stub.seen[2]["method"], "POST")
+
+    def test_raises_the_service_error_code_when_the_workspace_is_full(self):
+        Stub.routes[("POST", "/v1/browser/sessions")] = (
+            429,
+            {"error": "concurrency_limit", "message": "Stop a session before starting another."},
+        )
+        with self.assertRaises(CogniCloudError) as caught:
+            self.client().browser.sessions.create()
+        self.assertEqual(caught.exception.status, 429)
+        self.assertEqual(caught.exception.code, "concurrency_limit")
+
+    def test_countries_and_profiles_are_empty_until_they_exist(self):
+        Stub.routes[("GET", "/v1/browser/countries")] = (200, [])
+        Stub.routes[("GET", "/v1/browser/profiles")] = (200, [])
+        browser = self.client().browser
+        self.assertEqual(browser.countries(), [])
+        self.assertEqual(browser.profiles(), [])
+
+    def test_retries_reads_but_not_starts(self):
+        Stub.routes[("GET", "/v1/browser/sessions")] = (503, {"error": "service_unavailable", "message": "later"})
+        with self.assertRaises(CogniCloudError):
+            self.client(max_retries=2).browser.sessions.list()
+        self.assertEqual(len(Stub.seen), 3)
+        Stub.seen = []
+        Stub.routes[("POST", "/v1/browser/sessions")] = (503, {"error": "service_unavailable", "message": "later"})
+        with self.assertRaises(CogniCloudError):
+            self.client(max_retries=2).browser.sessions.create()
+        self.assertEqual(len(Stub.seen), 1)
+
+    def test_reports_an_unreachable_service_as_a_network_error(self):
+        probe = HTTPServer(("127.0.0.1", 0), Stub)
+        closed_port = probe.server_address[1]
+        probe.server_close()
+        client = CogniCloud("amadeus-token", browser_base_url=f"http://127.0.0.1:{closed_port}/v1/browser", max_retries=0)
+        with self.assertRaises(CogniCloudError) as caught:
+            client.browser.sessions.list()
+        self.assertEqual(caught.exception.status, 0)
+        self.assertEqual(caught.exception.code, "network_error")
+
+
+if __name__ == "__main__":
+    unittest.main()

cognicloud-0.9.0/tests/test_endpoint.py

@@ -0,0 +1,210 @@
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from cognicloud import (
+    CogniCloudError,
+    DeltaEvent,
+    DoneEvent,
+    EmbeddingsRequest,
+    EndpointClient,
+    ErrorEvent,
+    McpTool,
+    ResponsesRequest,
+)
+
+ANSWER = {
+    "id": "0c4e0e4a-0000-0000-0000-000000000000",
+    "model": "gpt-5-mini",
+    "output": "Valid.",
+    "finishReason": "stop",
+    "usage": {"inputTokens": 10, "outputTokens": 3, "totalTokens": 13},
+    "responseId": "resp_1",
+    "outputItems": [{"type": "mcp_call", "name": "validate_invoice_xml"}],
+}
+INVOKE_PATH = "/invoke/636f676e69636c6f7564/e1"
+
+
+class Stub(BaseHTTPRequestHandler):
+    """Answers from `routes[path]` as (status, content_type, body) and records each request."""
+
+    routes: dict = {}
+    seen: list = []
+
+    def do_POST(self):
+        length = int(self.headers.get("content-length", 0))
+        body = json.loads(self.rfile.read(length)) if length else None
+        Stub.seen.append(
+            {"path": self.path, "headers": {key.lower(): value for key, value in self.headers.items()}, "body": body}
+        )
+        status, content_type, raw = Stub.routes[self.path]
+        self.send_response(status)
+        self.send_header("content-type", content_type)
+        self.send_header("content-length", str(len(raw)))
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def log_message(self, *args):
+        pass
+
+
+def json_route(status, payload):
+    return (status, "application/json", json.dumps(payload).encode())
+
+
+def sse_route(text):
+    return (200, "text/event-stream", text.encode())
+
+
+class EndpointTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Stub)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def setUp(self):
+        Stub.routes = {}
+        Stub.seen = []
+
+    def client(self, **options):
+        return EndpointClient("cc_live_secret", endpoint_id="e1", base_url=self.base, **options)
+
+    def test_invoke_sends_the_credential_and_returns_the_answer(self):
+        Stub.routes[INVOKE_PATH] = json_route(200, ANSWER)
+        answer = self.client().invoke({"messages": [{"role": "user", "content": "Hi"}]})
+        self.assertEqual(answer.output, "Valid.")
+        self.assertEqual(answer.usage.total_tokens, 13)
+        self.assertEqual(Stub.seen[0]["headers"]["authorization"], "Bearer cc_live_secret")
+
+    def test_responses_sends_mcp_tools_by_label(self):
+        Stub.routes[INVOKE_PATH] = json_route(200, ANSWER)
+        request = ResponsesRequest(
+            input="Check this invoice.",
+            instructions="Be brief.",
+            tools=[McpTool("ksef", allowed_tools=["validate_invoice_xml"])],
+            tool_choice="required",
+        )
+        answer = self.client().responses(request)
+        self.assertEqual(answer.response_id, "resp_1")
+        self.assertEqual(len(answer.output_items), 1)
+        self.assertEqual(
+            Stub.seen[0]["body"],
+            {
+                "input": "Check this invoice.",
+                "instructions": "Be brief.",
+                "tools": [{"type": "mcp", "server_label": "ksef", "allowed_tools": ["validate_invoice_xml"]}],
+                "tool_choice": "required",
+            },
+        )
+
+    def test_a_caller_server_and_its_token_are_sent_and_the_token_is_hidden_in_repr(self):
+        Stub.routes[INVOKE_PATH] = json_route(200, ANSWER)
+        tool = McpTool("ksef", allowed_tools=["validate_invoice_xml"], server_url="https://ksef-api.flippi.co/mcp/v1", bearer_token="abc123")
+        self.client().responses(ResponsesRequest(input="Check this invoice.", tools=[tool]))
+        self.assertEqual(
+            Stub.seen[0]["body"]["tools"],
+            [
+                {
+                    "type": "mcp",
+                    "server_label": "ksef",
+                    "server_url": "https://ksef-api.flippi.co/mcp/v1",
+                    "headers": {"Authorization": "Bearer abc123"},
+                    "allowed_tools": ["validate_invoice_xml"],
+                }
+            ],
+        )
+        self.assertNotIn("abc123", repr(tool))
+
+    def test_extra_fields_are_sent_at_the_top_level(self):
+        Stub.routes[INVOKE_PATH] = json_route(200, ANSWER)
+        self.client().responses(ResponsesRequest(input="Hi", extra={"seed": 7, "reasoning": {"effort": "low"}}))
+        self.assertEqual(Stub.seen[0]["body"], {"input": "Hi", "seed": 7, "reasoning": {"effort": "low"}})
+
+    def test_responses_continues_with_previous_response_id(self):
+        Stub.routes[INVOKE_PATH] = json_route(200, {**ANSWER, "responseId": "resp_2"})
+        answer = self.client().responses(ResponsesRequest(input="And this one?", previous_response_id="resp_1"))
+        self.assertEqual(answer.response_id, "resp_2")
+        self.assertEqual(Stub.seen[0]["body"], {"input": "And this one?", "previous_response_id": "resp_1"})
+
+    def test_embeddings_return_one_vector_per_input(self):
+        Stub.routes[INVOKE_PATH + "/embeddings"] = json_route(
+            200,
+            {
+                "id": "x",
+                "model": "embed-small",
+                "data": [{"index": 0, "embedding": [0.1, 0.2]}, {"index": 1, "embedding": [0.3, 0.4]}],
+                "usage": {"inputTokens": 12, "outputTokens": 0, "totalTokens": 12},
+            },
+        )
+        result = self.client().embeddings(EmbeddingsRequest(["first", "second"], dimensions=256))
+        self.assertEqual(result.data[1].embedding, [0.3, 0.4])
+        self.assertEqual(Stub.seen[0]["body"], {"input": ["first", "second"], "dimensions": 256})
+
+    def test_invoke_is_never_retried_on_server_errors(self):
+        Stub.routes[INVOKE_PATH] = json_route(503, {"error": "gateway_unavailable", "message": "Try again."})
+        with self.assertRaises(CogniCloudError) as caught:
+            self.client(max_retries=3).invoke({"input": "Hi"})
+        self.assertEqual((caught.exception.status, caught.exception.code), (503, "gateway_unavailable"))
+        self.assertEqual(len(Stub.seen), 1)
+
+    def test_stream_yields_deltas_then_the_done_answer(self):
+        body = (
+            'event: delta\ndata: {"text":"Hel"}\n\n'
+            'event: delta\r\ndata: {"text":"lo"}\r\n\r\n'
+            f"event: done\ndata: {json.dumps({**ANSWER, 'output': 'Hello'})}\n\n"
+        )
+        Stub.routes[INVOKE_PATH] = sse_route(body)
+        events = list(self.client().stream({"messages": [{"role": "user", "content": "hi"}]}))
+        self.assertEqual(events[0], DeltaEvent("Hel"))
+        self.assertEqual(events[1], DeltaEvent("lo"))
+        self.assertIsInstance(events[2], DoneEvent)
+        self.assertEqual(events[2].answer.output, "Hello")
+        self.assertEqual(len(events), 3)
+        self.assertEqual(Stub.seen[0]["body"], {"messages": [{"role": "user", "content": "hi"}], "stream": True})
+        self.assertEqual(Stub.seen[0]["headers"]["accept"], "text/event-stream")
+
+    def test_stream_yields_a_provider_error_and_stops(self):
+        Stub.routes[INVOKE_PATH] = sse_route(
+            'event: delta\ndata: {"text":"Hi"}\n\n'
+            'event: error\ndata: {"code":"upstream_failure","message":"The provider did not finish the answer."}\n\n'
+        )
+        events = list(self.client().stream_responses(ResponsesRequest("x")))
+        self.assertEqual(events[1], ErrorEvent("upstream_failure", "The provider did not finish the answer."))
+        self.assertEqual(len(events), 2)
+
+    def test_stream_reports_stream_ended_when_it_closes_early(self):
+        Stub.routes[INVOKE_PATH] = sse_route('event: delta\ndata: {"text":"Hi"}\n\n')
+        events = list(self.client().stream({"input": "x"}))
+        self.assertEqual(events[1], ErrorEvent("stream_ended", "The stream ended before its final event."))
+
+    def test_a_refused_stream_raises_before_any_event(self):
+        Stub.routes[INVOKE_PATH] = json_route(
+            422, {"error": "invalid_request", "message": "Streaming needs an API version of 2024-10-21 or later."}
+        )
+        with self.assertRaises(CogniCloudError) as caught:
+            self.client().stream({"input": "x"})
+        self.assertEqual((caught.exception.status, caught.exception.code), (422, "invalid_request"))
+
+    def test_a_stream_is_never_retried(self):
+        Stub.routes[INVOKE_PATH] = json_route(503, {"error": "gateway_unavailable", "message": "Try again."})
+        with self.assertRaises(CogniCloudError):
+            self.client(max_retries=3).stream({"input": "x"})
+        self.assertEqual(len(Stub.seen), 1)
+
+    def test_an_endpoint_needs_exactly_one_address(self):
+        with self.assertRaises(ValueError):
+            EndpointClient("k")
+        with self.assertRaises(ValueError):
+            EndpointClient("k", endpoint_id="e1", url=self.base + INVOKE_PATH)
+
+
+if __name__ == "__main__":
+    unittest.main()