tileward 0.1.0__py3-none-any.whl

tileward/__init__.py

@@ -0,0 +1,55 @@
+"""Tileward: run large models on hardware you own, governed.
+
+The library and the `twcli` command are the same package. Two lines to a first call:
+
+```python
+from tileward import Tileward
+
+tw = Tileward(api_key="tw_live_...")     # or set TILEWARD_API_KEY
+print(tw.chat.say("Say hello in one sentence."))
+```
+
+Four capabilities hang off the client:
+
+  `tw.models` / `tw.chat`   Tileward Models — an OpenAI-compatible chat surface.
+  `tw.guard`                Tileward Governance — allow/deny before the model writes a token.
+  `tw.context`              Tileward Context — recall the slice of history a question needs.
+  `tw.documents`            Tileward Documents — answers from your own files.
+
+plus `tw.keys` and `tw.account`, which manage the account itself and need a console session from
+`twcli auth login` rather than an API key.
+"""
+
+from ._version import __version__
+from .client import AsyncTileward, Tileward, openai_base_url
+from .config import Config
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConfigError,
+    ConnectionError_,
+    GuardRefusal,
+    InsufficientBalanceError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TilewardError,
+)
+
+__all__ = [
+    "Tileward",
+    "AsyncTileward",
+    "Config",
+    "openai_base_url",
+    "TilewardError",
+    "ConfigError",
+    "APIError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ConnectionError_",
+    "GuardRefusal",
+    "__version__",
+]

tileward/_http.py

@@ -0,0 +1,365 @@
+"""HTTP transport: auth, retries, error mapping, SSE.
+
+Retries cover connection failures, 429 and 5xx only. Streaming responses are not
+retried once bytes have arrived.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import random
+import time
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from . import errors
+from ._version import __version__
+
+DEFAULT_TIMEOUT = 60.0
+# Generation is slow by nature: a long completion legitimately takes minutes, and a read timeout
+# that fires mid-answer bills for tokens the caller never sees.
+STREAM_TIMEOUT = 600.0
+DEFAULT_MAX_RETRIES = 2
+RETRY_STATUS = frozenset({408, 409, 429, 500, 502, 503, 504})
+
+USER_AGENT = f"tileward-python/{__version__}"
+
+AuthMode = str  # "key" | "session" | "none"
+
+
+def _user_agent(suffix: Optional[str] = None) -> str:
+    return f"{USER_AGENT} ({suffix})" if suffix else USER_AGENT
+
+
+def _decode(response: httpx.Response) -> Any:
+    ctype = response.headers.get("content-type", "")
+    if "json" in ctype:
+        try:
+            return response.json()
+        except ValueError:
+            pass
+    text = response.text
+    try:
+        return _json.loads(text)
+    except ValueError:
+        return text
+
+
+def _request_id(response: httpx.Response) -> Optional[str]:
+    for header in ("x-request-id", "x-tileward-request-id", "cf-ray"):
+        value = response.headers.get(header)
+        if value:
+            return value
+    return None
+
+
+def _retry_after(response: httpx.Response) -> Optional[float]:
+    raw = response.headers.get("retry-after")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int, retry_after: Optional[float]) -> float:
+    """Exponential with full jitter, floored by any Retry-After the server sent.
+
+    Full jitter rather than a fixed doubling: a fleet of clients that all retry at exactly 1s, 2s,
+    4s re-creates the burst that caused the 429 in the first place.
+    """
+    if retry_after is not None:
+        return min(retry_after, 60.0)
+    return min(0.5 * (2**attempt), 8.0) * (0.5 + random.random() / 2)
+
+
+def _iter_sse(lines: Iterator[str]) -> Iterator[Dict[str, Any]]:
+    """Yield decoded `data:` payloads from an SSE stream, stopping at `[DONE]`.
+
+    The sentinel is not JSON, so a caller that json.loads every data line crashes on the last one.
+    """
+    for raw in lines:
+        line = raw.strip()
+        if not line or line.startswith(":") or not line.startswith("data:"):
+            continue
+        payload = line[len("data:") :].strip()
+        if payload == "[DONE]":
+            return
+        try:
+            yield _json.loads(payload)
+        except ValueError:
+            continue
+
+
+class _Base:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        console_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        session_token: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        user_agent_suffix: Optional[str] = None,
+        default_headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        # TWO HOSTS, AND THEY DO NOT OVERLAP. `api.tileward.com` serves `/v1` only and answers
+        # anything else with 404 `wrong_host`. The session surface — `/auth/*` and every
+        # `/api/*` — lives on the console host. Routing by auth mode is what keeps that
+        # invisible to callers.
+        self.console_url = (console_url or base_url).rstrip("/")
+        self.api_key = api_key
+        self.session_token = session_token
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self.default_headers = dict(default_headers or {})
+        self.user_agent = _user_agent(user_agent_suffix)
+
+    def _url(self, path: str, auth: AuthMode = "key", host: Optional[str] = None) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        # `session` always means the console. `none` is only used by the device-code flow, which
+        # is also console-only, so it routes there too — a caller wanting the api host with no
+        # credential passes host="api" explicitly.
+        which = host or ("console" if auth in ("session", "none") else "api")
+        root = self.console_url if which == "console" else self.base_url
+        return f"{root}/{path.lstrip('/')}"
+
+    def _headers(self, auth: AuthMode, extra: Optional[Mapping[str, str]]) -> Dict[str, str]:
+        headers: Dict[str, str] = {
+            "User-Agent": self.user_agent,
+            "Accept": "application/json",
+        }
+        headers.update(self.default_headers)
+        if auth == "key":
+            if not self.api_key:
+                raise errors.ConfigError(
+                    "No API key. Set TILEWARD_API_KEY, pass api_key=..., or run "
+                    "`twcli auth login` and mint one with `twcli keys create`."
+                )
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        elif auth == "session":
+            if not self.session_token:
+                raise errors.ConfigError(
+                    "This needs a signed-in console session, not an API key. "
+                    "Run `twcli auth login`."
+                )
+            # The account surface authenticates on the session COOKIE, not a bearer header —
+            # `_session_sub` in the gateway reads `request.cookies`. Sending it as a bearer token
+            # authenticates nothing and returns a confusing 401.
+            headers["Cookie"] = f"tw_session={self.session_token}"
+        if extra:
+            headers.update({k: v for k, v in extra.items() if v is not None})
+        return headers
+
+    def _raise(self, response: httpx.Response) -> None:
+        raise errors.from_response(response.status_code, _decode(response), _request_id(response))
+
+
+class Transport(_Base):
+    """Synchronous transport."""
+
+    def __init__(self, *args: Any, client: Optional[httpx.Client] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client = client
+        self._owns_client = client is None
+
+    @property
+    def client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(timeout=self.timeout, follow_redirects=True)
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None and self._owns_client:
+            self._client.close()
+            self._client = None
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        auth: AuthMode = "key",
+        timeout: Optional[float] = None,
+        retries: Optional[int] = None,
+        raw: bool = False,
+        host: Optional[str] = None,
+    ) -> Any:
+        url = self._url(path, auth, host)
+        hdrs = self._headers(auth, headers)
+        budget = self.max_retries if retries is None else max(0, retries)
+        attempt = 0
+        while True:
+            try:
+                response = self.client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=_clean_params(params),
+                    headers=hdrs,
+                    timeout=timeout or self.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt >= budget:
+                    raise errors.ConnectionError_(f"{method} {url} timed out: {exc}") from exc
+            except httpx.HTTPError as exc:
+                if attempt >= budget:
+                    raise errors.ConnectionError_(f"{method} {url} failed: {exc}") from exc
+            else:
+                if response.status_code in RETRY_STATUS and attempt < budget:
+                    time.sleep(_backoff(attempt, _retry_after(response)))
+                    attempt += 1
+                    continue
+                if response.status_code >= 400:
+                    self._raise(response)
+                return response if raw else _decode(response)
+            time.sleep(_backoff(attempt, None))
+            attempt += 1
+
+    def stream_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        auth: AuthMode = "key",
+        timeout: Optional[float] = None,
+        host: Optional[str] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        url = self._url(path, auth, host)
+        hdrs = self._headers(auth, headers)
+        hdrs["Accept"] = "text/event-stream"
+        try:
+            with self.client.stream(
+                method, url, json=json, headers=hdrs, timeout=timeout or STREAM_TIMEOUT
+            ) as response:
+                if response.status_code >= 400:
+                    response.read()
+                    self._raise(response)
+                yield from _iter_sse(response.iter_lines())
+        except httpx.HTTPError as exc:
+            raise errors.ConnectionError_(f"{method} {url} stream failed: {exc}") from exc
+
+
+class AsyncTransport(_Base):
+    """Asynchronous transport. Same policy, same errors."""
+
+    def __init__(
+        self, *args: Any, client: Optional[httpx.AsyncClient] = None, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._client = client
+        self._owns_client = client is None
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.timeout, follow_redirects=True)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+            self._client = None
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        auth: AuthMode = "key",
+        timeout: Optional[float] = None,
+        retries: Optional[int] = None,
+        raw: bool = False,
+        host: Optional[str] = None,
+    ) -> Any:
+        import asyncio
+
+        url = self._url(path, auth, host)
+        hdrs = self._headers(auth, headers)
+        budget = self.max_retries if retries is None else max(0, retries)
+        attempt = 0
+        while True:
+            try:
+                response = await self.client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=_clean_params(params),
+                    headers=hdrs,
+                    timeout=timeout or self.timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt >= budget:
+                    raise errors.ConnectionError_(f"{method} {url} timed out: {exc}") from exc
+            except httpx.HTTPError as exc:
+                if attempt >= budget:
+                    raise errors.ConnectionError_(f"{method} {url} failed: {exc}") from exc
+            else:
+                if response.status_code in RETRY_STATUS and attempt < budget:
+                    await asyncio.sleep(_backoff(attempt, _retry_after(response)))
+                    attempt += 1
+                    continue
+                if response.status_code >= 400:
+                    self._raise(response)
+                return response if raw else _decode(response)
+            await asyncio.sleep(_backoff(attempt, None))
+            attempt += 1
+
+    async def stream_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        auth: AuthMode = "key",
+        timeout: Optional[float] = None,
+        host: Optional[str] = None,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        url = self._url(path, auth, host)
+        hdrs = self._headers(auth, headers)
+        hdrs["Accept"] = "text/event-stream"
+        try:
+            async with self.client.stream(
+                method, url, json=json, headers=hdrs, timeout=timeout or STREAM_TIMEOUT
+            ) as response:
+                if response.status_code >= 400:
+                    await response.aread()
+                    self._raise(response)
+                async for raw_line in response.aiter_lines():
+                    line = raw_line.strip()
+                    if not line.startswith("data:"):
+                        continue
+                    payload = line[len("data:") :].strip()
+                    if payload == "[DONE]":
+                        return
+                    try:
+                        yield _json.loads(payload)
+                    except ValueError:
+                        continue
+        except httpx.HTTPError as exc:
+            raise errors.ConnectionError_(f"{method} {url} stream failed: {exc}") from exc
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Drop None values so an unset optional does not become the literal string 'None'."""
+    if not params:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+Streamable = Union[Iterator[Dict[str, Any]], AsyncIterator[Dict[str, Any]]]

tileward/_mcp.py

@@ -0,0 +1,251 @@
+"""Minimal MCP client for Tileward Context.
+
+The transport is stateless streamable-HTTP, so a `tools/call` needs no initialize
+handshake. The conversation header goes out under both spellings; one deployed
+generation reads only the older name.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from collections.abc import Mapping
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import errors
+
+JSONRPC_VERSION = "2.0"
+# Streamable HTTP may answer with either a JSON body or an SSE stream; the spec allows both and
+# the server picks. Asking for both is what keeps the client working across that choice.
+MCP_ACCEPT = "application/json, text/event-stream"
+
+
+def build_payload(tool: str, arguments: Mapping[str, Any], request_id: int = 1) -> Dict[str, Any]:
+    return {
+        "jsonrpc": JSONRPC_VERSION,
+        "id": request_id,
+        "method": "tools/call",
+        "params": {
+            "name": tool,
+            "arguments": {k: v for k, v in arguments.items() if v is not None},
+        },
+    }
+
+
+def conversation_headers(conversation: Optional[str]) -> Dict[str, str]:
+    if not conversation:
+        return {}
+    value = str(conversation).strip()
+    if not value:
+        return {}
+    return {"X-Tileward-Conversation": value, "X-Twinkle-Conversation": value}
+
+
+def parse_body(status: int, content_type: str, text: str) -> Dict[str, Any]:
+    """Decode a streamable-HTTP response into the JSON-RPC envelope."""
+    if "text/event-stream" in (content_type or ""):
+        envelope: Optional[Dict[str, Any]] = None
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line.startswith("data:"):
+                continue
+            payload = line[len("data:") :].strip()
+            if not payload or payload == "[DONE]":
+                continue
+            try:
+                candidate = _json.loads(payload)
+            except ValueError:
+                continue
+            if isinstance(candidate, dict) and ("result" in candidate or "error" in candidate):
+                envelope = candidate
+        if envelope is None:
+            raise errors.APIError(
+                "Context returned an event stream with no JSON-RPC response in it.",
+                status=status,
+                body={"raw": text[:500]},
+            )
+        return envelope
+    try:
+        decoded = _json.loads(text)
+    except ValueError as exc:
+        raise errors.APIError(
+            f"Context returned a body that is not JSON: {text[:200]}", status=status
+        ) from exc
+    if not isinstance(decoded, dict):
+        raise errors.APIError("Context returned a JSON value that is not an object.", status=status)
+    return decoded
+
+
+def unwrap(envelope: Mapping[str, Any]) -> Any:
+    """Pull a tool's return value out of the JSON-RPC + MCP content wrapping.
+
+    Three failure shapes have to be told apart, and they arrive at three different depths:
+      * a JSON-RPC `error` — the method or the arguments were wrong;
+      * `result.isError` — the tool ran and refused (a bad conversation id, a missing document);
+      * a result with no content — nothing to unwrap, and returning `{}` would look like success.
+    """
+    if "error" in envelope:
+        err = envelope.get("error") or {}
+        message = str(err.get("message") or "Context returned a JSON-RPC error.")
+        raise errors.APIError(message, code=str(err.get("code") or ""), body=dict(envelope))
+
+    result = envelope.get("result")
+    if not isinstance(result, dict):
+        raise errors.APIError("Context returned no result.", body=dict(envelope))
+
+    content = result.get("content") or []
+    text = ""
+    if isinstance(content, list) and content:
+        first = content[0]
+        if isinstance(first, dict):
+            text = str(first.get("text") or "")
+
+    if result.get("isError"):
+        raise errors.APIError(text or "The Context tool reported an error.", body=dict(envelope))
+
+    # A tool that returns a dict is serialised as JSON inside a text block; one that returns a
+    # string is that string. Both are legitimate, so a failed parse is data, not an error.
+    if not text:
+        structured = result.get("structuredContent")
+        return structured if structured is not None else {}
+    try:
+        return _json.loads(text)
+    except ValueError:
+        return text
+
+
+class ContextTransport:
+    """Synchronous MCP-over-HTTP calls against the Context endpoint."""
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        api_key: Optional[str],
+        timeout: float = 60.0,
+        user_agent: str = "tileward-python",
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._client = client
+        self._owns_client = client is None
+        self._counter = 0
+
+    @property
+    def client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(timeout=self.timeout, follow_redirects=True)
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None and self._owns_client:
+            self._client.close()
+            self._client = None
+
+    def _headers(self, conversation: Optional[str]) -> Dict[str, str]:
+        if not self.api_key:
+            raise errors.ConfigError(
+                "Tileward Context needs an API key. Set TILEWARD_API_KEY or pass api_key=..."
+            )
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": MCP_ACCEPT,
+            "User-Agent": self.user_agent,
+        }
+        headers.update(conversation_headers(conversation))
+        return headers
+
+    def call(
+        self,
+        tool: str,
+        arguments: Optional[Mapping[str, Any]] = None,
+        *,
+        conversation: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        self._counter += 1
+        payload = build_payload(tool, arguments or {}, self._counter)
+        try:
+            response = self.client.post(
+                self.url,
+                json=payload,
+                headers=self._headers(conversation),
+                timeout=timeout or self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise errors.ConnectionError_(f"Context call to {self.url} failed: {exc}") from exc
+        if response.status_code >= 400:
+            # A 401 here is its own thing: the Context endpoint takes a Tileward API key, and the
+            # error it returns points OAuth clients at a different path. Surface it verbatim.
+            raise errors.from_response(
+                response.status_code,
+                _safe_json(response.text),
+                response.headers.get("x-request-id"),
+            )
+        envelope = parse_body(
+            response.status_code, response.headers.get("content-type", ""), response.text
+        )
+        return unwrap(envelope)
+
+
+class AsyncContextTransport(ContextTransport):
+    """Asynchronous twin. Shares every decoding rule above."""
+
+    def __init__(self, *args: Any, client: Optional[httpx.AsyncClient] = None, **kwargs: Any):
+        kwargs.pop("client", None)
+        super().__init__(*args, **kwargs)
+        self._aclient = client
+        self._owns_aclient = client is None
+
+    @property
+    def aclient(self) -> httpx.AsyncClient:
+        if self._aclient is None:
+            self._aclient = httpx.AsyncClient(timeout=self.timeout, follow_redirects=True)
+        return self._aclient
+
+    async def aclose(self) -> None:
+        if self._aclient is not None and self._owns_aclient:
+            await self._aclient.aclose()
+            self._aclient = None
+
+    async def acall(
+        self,
+        tool: str,
+        arguments: Optional[Mapping[str, Any]] = None,
+        *,
+        conversation: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        self._counter += 1
+        payload = build_payload(tool, arguments or {}, self._counter)
+        try:
+            response = await self.aclient.post(
+                self.url,
+                json=payload,
+                headers=self._headers(conversation),
+                timeout=timeout or self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise errors.ConnectionError_(f"Context call to {self.url} failed: {exc}") from exc
+        if response.status_code >= 400:
+            raise errors.from_response(
+                response.status_code,
+                _safe_json(response.text),
+                response.headers.get("x-request-id"),
+            )
+        envelope = parse_body(
+            response.status_code, response.headers.get("content-type", ""), response.text
+        )
+        return unwrap(envelope)
+
+
+def _safe_json(text: str) -> Any:
+    try:
+        return _json.loads(text)
+    except ValueError:
+        return text

tileward/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"