clinia-context-engine 0.8.0__py3-none-any.whl

clinia_context_engine/__init__.py

@@ -0,0 +1,28 @@
+from . import resources as resources
+from ._auth import (
+    AsyncClientCredentialsTokenProvider,
+    ClientCredentials,
+    ClientCredentialsTokenProvider,
+)
+from ._errors import APIConnectionError, APIStatusError, APITimeoutError, ContextEngineError
+from ._http import AsyncHttpClient, AsyncTokenProvider, HttpClient, TokenProvider
+from .client import AsyncContextEngineClient, ContextEngineClient
+from .generated import models as models
+
+__all__ = [
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncClientCredentialsTokenProvider",
+    "AsyncContextEngineClient",
+    "AsyncHttpClient",
+    "AsyncTokenProvider",
+    "ClientCredentials",
+    "ClientCredentialsTokenProvider",
+    "ContextEngineClient",
+    "ContextEngineError",
+    "HttpClient",
+    "TokenProvider",
+    "models",
+    "resources",
+]

clinia_context_engine/_auth.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Literal
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._errors import ContextEngineError
+
+__all__ = [
+    "AsyncClientCredentialsTokenProvider",
+    "ClientCredentials",
+    "ClientCredentialsTokenProvider",
+]
+
+# Clinia's authorization server, applied when a config names neither a
+# `token_url` nor an `issuer` — so `ClientCredentials(client_id, client_secret)`
+# is a complete config for a Clinia workspace.
+#
+# The resource indicator is only defaulted alongside the token URL: it is an
+# RFC 8707 indicator naming Clinia's protected resource, and sending it to
+# somebody else's authorization server would be wrong.
+CLINIA_OAUTH_TOKEN_URL = "https://console.clinia.cloud/api/auth/oauth2/token"
+CLINIA_OAUTH_RESOURCE = "https://console.clinia.cloud"
+
+DEFAULT_EXPIRY_MARGIN = 60.0
+# Fallback lifetime when the token endpoint omits `expires_in`.
+DEFAULT_TTL = 300.0
+
+
+@dataclass(frozen=True, kw_only=True)
+class ClientCredentials:
+    """OAuth2 client-credentials configuration.
+
+    For a Clinia workspace, `client_id` + `client_secret` is enough — the token
+    endpoint and `resource` indicator default to Clinia's authorization server.
+    Naming an `issuer` instead locates a different authorization server by
+    OIDC/OAuth2 discovery; naming a `token_url` points at one explicitly.
+    """
+
+    client_id: str
+    client_secret: str
+    token_url: str | None = None
+    issuer: str | None = None
+    # Discovery transformation used when `issuer` is given: OIDC (default) or
+    # RFC 8414.
+    discovery_algorithm: Literal["oidc", "oauth2"] = "oidc"
+    # RFC 8707 resource indicator naming the protected resource the token is
+    # for.
+    resource: str | None = None
+    # `audience` parameter used by some IdPs (e.g. Auth0).
+    audience: str | None = None
+    # Space-delimited scopes.
+    scope: str | None = None
+    # How the credentials are presented to the token endpoint: `post` (the
+    # default, what Clinia's authorization server expects) sends them in the
+    # request body; `basic` sends them in the Authorization header
+    # (RFC 6749 §2.3.1).
+    auth_method: Literal["basic", "post"] = "post"
+    # Refresh the token this many seconds before it actually expires, so a
+    # token is never handed out mid-flight of expiring.
+    expiry_margin: float = DEFAULT_EXPIRY_MARGIN
+
+
+def _discovery_url(config: ClientCredentials) -> str:
+    assert config.issuer is not None
+    if config.discovery_algorithm == "oauth2":
+        # RFC 8414: the well-known segment is inserted between host and path.
+        parts = urlsplit(config.issuer)
+        path = parts.path.rstrip("/")
+        return f"{parts.scheme}://{parts.netloc}/.well-known/oauth-authorization-server{path}"
+    return config.issuer.rstrip("/") + "/.well-known/openid-configuration"
+
+
+def _token_request_args(config: ClientCredentials, token_endpoint: str) -> dict[str, Any]:
+    uses_clinia_auth_server = config.token_url is None and config.issuer is None
+    resource = config.resource or (CLINIA_OAUTH_RESOURCE if uses_clinia_auth_server else None)
+
+    data: dict[str, str] = {"grant_type": "client_credentials"}
+    if resource:
+        data["resource"] = resource
+    if config.audience:
+        data["audience"] = config.audience
+    if config.scope:
+        data["scope"] = config.scope
+
+    args: dict[str, Any] = {"url": token_endpoint, "data": data}
+    if config.auth_method == "basic":
+        args["auth"] = httpx.BasicAuth(config.client_id, config.client_secret)
+    else:
+        data["client_id"] = config.client_id
+        data["client_secret"] = config.client_secret
+    return args
+
+
+def _parse_token_response(response: httpx.Response) -> tuple[str, float]:
+    """Returns the access token and the absolute time it should be refreshed."""
+    if response.is_error:
+        detail: str
+        try:
+            payload = response.json()
+            detail = str(payload.get("error", response.reason_phrase))
+            if payload.get("error_description"):
+                detail += f" — {payload['error_description']}"
+        except ValueError:
+            detail = response.reason_phrase
+        raise ContextEngineError(
+            f"client_credentials token request failed: {response.status_code} {detail}"
+        )
+    payload = response.json()
+    token = payload.get("access_token")
+    if not isinstance(token, str) or not token:
+        raise ContextEngineError(
+            "client_credentials token request failed: response carries no access_token"
+        )
+    ttl = float(payload["expires_in"]) if payload.get("expires_in") else DEFAULT_TTL
+    return token, ttl
+
+
+def _parse_discovery_response(response: httpx.Response) -> str:
+    if response.is_error:
+        raise ContextEngineError(f"authorization server discovery failed: {response.status_code}")
+    endpoint = response.json().get("token_endpoint")
+    if not isinstance(endpoint, str) or not endpoint:
+        raise ContextEngineError(
+            "authorization server discovery failed: metadata carries no token_endpoint"
+        )
+    return endpoint
+
+
+class _TokenState:
+    """Cached token plus the resolved token endpoint, shared by both providers."""
+
+    def __init__(self, config: ClientCredentials) -> None:
+        self.config = config
+        # Discovery only when an issuer is named and no explicit endpoint
+        # overrides it; with neither, Clinia's endpoint is the default.
+        if config.token_url or config.issuer is None:
+            self.token_endpoint: str | None = config.token_url or CLINIA_OAUTH_TOKEN_URL
+        else:
+            self.token_endpoint = None
+        self.token: str | None = None
+        # Absolute monotonic time at which the cached token is considered stale.
+        self.refresh_at = 0.0
+
+    def fresh_token(self) -> str | None:
+        if self.token is not None and time.monotonic() < self.refresh_at:
+            return self.token
+        return None
+
+    def store(self, token: str, ttl: float) -> str:
+        self.token = token
+        self.refresh_at = time.monotonic() + max(0.0, ttl - self.config.expiry_margin)
+        return token
+
+
+class ClientCredentialsTokenProvider:
+    """Callable token provider backed by the OAuth2 client-credentials grant.
+
+    Caches the access token until it is within `expiry_margin` of expiry;
+    concurrent callers share one token request. When configured with an
+    `issuer`, the authorization server metadata is discovered once and
+    memoized.
+    """
+
+    def __init__(
+        self, config: ClientCredentials, *, http_client: httpx.Client | None = None
+    ) -> None:
+        self._state = _TokenState(config)
+        self._http_client = http_client
+        self._lock = threading.Lock()
+
+    def __call__(self) -> str:
+        token = self._state.fresh_token()
+        if token is not None:
+            return token
+        with self._lock:
+            token = self._state.fresh_token()
+            if token is not None:
+                return token
+            return self._fetch()
+
+    def _fetch(self) -> str:
+        client = self._http_client or httpx.Client()
+        try:
+            if self._state.token_endpoint is None:
+                response = client.get(_discovery_url(self._state.config))
+                self._state.token_endpoint = _parse_discovery_response(response)
+            args = _token_request_args(self._state.config, self._state.token_endpoint)
+            token, ttl = _parse_token_response(client.post(**args))
+            return self._state.store(token, ttl)
+        finally:
+            if self._http_client is None:
+                client.close()
+
+
+class AsyncClientCredentialsTokenProvider:
+    """Async twin of `ClientCredentialsTokenProvider`."""
+
+    def __init__(
+        self, config: ClientCredentials, *, http_client: httpx.AsyncClient | None = None
+    ) -> None:
+        self._state = _TokenState(config)
+        self._http_client = http_client
+        self._lock = asyncio.Lock()
+
+    async def __call__(self) -> str:
+        token = self._state.fresh_token()
+        if token is not None:
+            return token
+        async with self._lock:
+            token = self._state.fresh_token()
+            if token is not None:
+                return token
+            return await self._fetch()
+
+    async def _fetch(self) -> str:
+        client = self._http_client or httpx.AsyncClient()
+        try:
+            if self._state.token_endpoint is None:
+                response = await client.get(_discovery_url(self._state.config))
+                self._state.token_endpoint = _parse_discovery_response(response)
+            args = _token_request_args(self._state.config, self._state.token_endpoint)
+            token, ttl = _parse_token_response(await client.post(**args))
+            return self._state.store(token, ttl)
+        finally:
+            if self._http_client is None:
+                await client.aclose()

clinia_context_engine/_errors.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import httpx
+
+from .generated.models import ApiError
+
+__all__ = [
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "ContextEngineError",
+]
+
+
+class ContextEngineError(Exception):
+    """Base class for every error raised by this client."""
+
+
+class APIConnectionError(ContextEngineError):
+    """The request never produced an HTTP response."""
+
+    def __init__(self, message: str, *, request: httpx.Request) -> None:
+        super().__init__(message)
+        self.request = request
+
+
+class APITimeoutError(APIConnectionError):
+    def __init__(self, *, request: httpx.Request) -> None:
+        super().__init__("Request timed out.", request=request)
+
+
+class APIStatusError(ContextEngineError):
+    """A non-2xx HTTP response.
+
+    `error` carries the server's parsed error envelope when the body is a valid
+    `ApiError`; `body` always carries the raw response text.
+    """
+
+    def __init__(self, *, response: httpx.Response, error: ApiError | None) -> None:
+        detail = f" — {error.type}: {error.message}" if error else ""
+        super().__init__(f"{response.status_code} {response.reason_phrase}{detail}")
+        self.response = response
+        self.status_code = response.status_code
+        self.error = error
+        self.body = response.text

clinia_context_engine/_http.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any, TypeVar, overload
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from ._errors import APIConnectionError, APIStatusError, APITimeoutError
+from .generated.models import ApiError
+
+__all__ = ["AsyncHttpClient", "AsyncTokenProvider", "HttpClient", "TokenProvider"]
+
+TokenProvider = Callable[[], str]
+AsyncTokenProvider = Callable[[], Awaitable[str]]
+
+DEFAULT_TIMEOUT = httpx.Timeout(60.0)
+
+T = TypeVar("T")
+
+
+def _substitute_path(path: str, path_params: Mapping[str, Any] | None) -> str:
+    if not path_params:
+        return path
+    for name, value in path_params.items():
+        path = path.replace("{" + name + "}", quote(str(value), safe=""))
+    return path
+
+
+def _prepare_query(query: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    """Omitted (None) parameters are dropped rather than sent as empty values."""
+    if query is None:
+        return None
+    prepared = {name: value for name, value in query.items() if value is not None}
+    return prepared or None
+
+
+def _prepare_json(body: Any) -> Any:
+    if isinstance(body, BaseModel):
+        return body.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    return body
+
+
+def _parse_response(response: httpx.Response, cast_to: TypeAdapter[T] | None) -> T | None:
+    if cast_to is None:
+        return None
+    # Operations that also declare a text response (e.g. a Markdown rendering
+    # behind a `format` query parameter) carry `str` in `cast_to`'s union, so a
+    # non-JSON response validates as its text.
+    if "json" in response.headers.get("Content-Type", ""):
+        return cast_to.validate_json(response.content)
+    return cast_to.validate_python(response.text)
+
+
+def _status_error(response: httpx.Response) -> APIStatusError:
+    try:
+        error = ApiError.model_validate_json(response.content)
+    except ValidationError:
+        error = None
+    return APIStatusError(response=response, error=error)
+
+
+class _RequestBuilder:
+    """Request construction shared by the sync and async clients."""
+
+    def __init__(self, base_url: str) -> None:
+        self._base_url = base_url.rstrip("/")
+
+    def build_args(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: Mapping[str, Any] | None,
+        query: Mapping[str, Any] | None,
+        json: Any,
+        content: str | bytes | None,
+        content_type: str | None,
+        token: str | None,
+    ) -> dict[str, Any]:
+        headers: dict[str, str] = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        if content_type is not None:
+            headers["Content-Type"] = content_type
+
+        args: dict[str, Any] = {
+            "method": method,
+            "url": self._base_url + _substitute_path(path, path_params),
+            "headers": headers,
+        }
+        params = _prepare_query(query)
+        if params is not None:
+            args["params"] = params
+        if json is not None:
+            args["json"] = _prepare_json(json)
+        if content is not None:
+            args["content"] = content
+        return args
+
+
+class HttpClient:
+    """Thin typed transport: one `request()` the generated resources call.
+
+    Owns an `httpx.Client` unless one is injected; injected clients are not
+    closed by `close()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token_provider: TokenProvider | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._builder = _RequestBuilder(base_url)
+        self._token_provider = token_provider
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout or DEFAULT_TIMEOUT)
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: TypeAdapter[T],
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        json: Any = None,
+        content: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> T: ...
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: None,
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        json: Any = None,
+        content: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> None: ...
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: TypeAdapter[T] | None,
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        json: Any = None,
+        content: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> T | None:
+        token = self._token_provider() if self._token_provider else None
+        args = self._builder.build_args(
+            method,
+            path,
+            path_params=path_params,
+            query=query,
+            json=json,
+            content=content,
+            content_type=content_type,
+            token=token,
+        )
+        try:
+            response = self._client.request(**args)
+        except httpx.TimeoutException as err:
+            raise APITimeoutError(request=err.request) from err
+        except httpx.TransportError as err:
+            raise APIConnectionError(str(err), request=err.request) from err
+        if response.is_error:
+            raise _status_error(response)
+        return _parse_response(response, cast_to)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncHttpClient:
+    """Async twin of `HttpClient`, backed by `httpx.AsyncClient`."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token_provider: AsyncTokenProvider | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._builder = _RequestBuilder(base_url)
+        self._token_provider = token_provider
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout or DEFAULT_TIMEOUT)
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: TypeAdapter[T],
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        json: Any = None,
+        content: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> T: ...
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: None,
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        json: Any = None,
+        content: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> None: ...
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        cast_to: TypeAdapter[T] | None,
+        path_params: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        json: Any = None,
+        content: str | bytes | None = None,
+        content_type: str | None = None,
+    ) -> T | None:
+        token = await self._token_provider() if self._token_provider else None
+        args = self._builder.build_args(
+            method,
+            path,
+            path_params=path_params,
+            query=query,
+            json=json,
+            content=content,
+            content_type=content_type,
+            token=token,
+        )
+        try:
+            response = await self._client.request(**args)
+        except httpx.TimeoutException as err:
+            raise APITimeoutError(request=err.request) from err
+        except httpx.TransportError as err:
+            raise APIConnectionError(str(err), request=err.request) from err
+        if response.is_error:
+            raise _status_error(response)
+        return _parse_response(response, cast_to)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()

clinia_context_engine/client.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import httpx
+
+from ._auth import (
+    AsyncClientCredentialsTokenProvider,
+    ClientCredentials,
+    ClientCredentialsTokenProvider,
+)
+from ._http import AsyncHttpClient, AsyncTokenProvider, HttpClient, TokenProvider
+from .resources import (
+    AsyncGraphResource,
+    AsyncInfoResource,
+    AsyncIngestResource,
+    AsyncPatientsResource,
+    AsyncSessionsResource,
+    AsyncVFSResource,
+    GraphResource,
+    InfoResource,
+    IngestResource,
+    PatientsResource,
+    SessionsResource,
+    VFSResource,
+)
+
+__all__ = ["AsyncContextEngineClient", "ContextEngineClient"]
+
+
+class ContextEngineClient:
+    """Synchronous client for the Context Engine API.
+
+    `auth` accepts either a `ClientCredentials` config — the common case, the
+    client then handles token acquisition, caching, and refresh — or a token
+    callable for full control (a token from elsewhere, a different grant, or a
+    custom refresh strategy), called per request and attached as
+    `Authorization: Bearer <token>`. Omit for an unsecured server.
+
+    Owns network resources; use it as a context manager or call `close()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth: ClientCredentials | TokenProvider | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        token_provider: TokenProvider | None
+        if isinstance(auth, ClientCredentials):
+            token_provider = ClientCredentialsTokenProvider(auth)
+        else:
+            token_provider = auth
+
+        self.http = HttpClient(
+            base_url=base_url,
+            token_provider=token_provider,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.graph = GraphResource(self.http)
+        self.info = InfoResource(self.http)
+        self.ingest = IngestResource(self.http)
+        self.patients = PatientsResource(self.http)
+        self.sessions = SessionsResource(self.http)
+        self.vfs = VFSResource(self.http)
+
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> ContextEngineClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncContextEngineClient:
+    """Async twin of `ContextEngineClient`."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth: ClientCredentials | AsyncTokenProvider | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        token_provider: AsyncTokenProvider | None
+        if isinstance(auth, ClientCredentials):
+            token_provider = AsyncClientCredentialsTokenProvider(auth)
+        else:
+            token_provider = auth
+
+        self.http = AsyncHttpClient(
+            base_url=base_url,
+            token_provider=token_provider,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.graph = AsyncGraphResource(self.http)
+        self.info = AsyncInfoResource(self.http)
+        self.ingest = AsyncIngestResource(self.http)
+        self.patients = AsyncPatientsResource(self.http)
+        self.sessions = AsyncSessionsResource(self.http)
+        self.vfs = AsyncVFSResource(self.http)
+
+    async def aclose(self) -> None:
+        await self.http.aclose()
+
+    async def __aenter__(self) -> AsyncContextEngineClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()

clinia_context_engine/generated/__init__.py

@@ -0,0 +1,3 @@
+from . import models as models
+
+__all__ = ["models"]