clark-platform-client 0.1.0__py3-none-any.whl

clark_platform/__init__.py

@@ -0,0 +1,61 @@
+"""Typed sync/async Python client for the Clark Platform API.
+
+See https://www.clarkchat.com and ``platform/clients/API_CONTRACT.md`` in the
+Clark monorepo for the full wire contract this client implements.
+"""
+
+from .async_client import AsyncClarkClient
+from .client import ClarkClient
+from .errors import ClarkApiError
+from .models import (
+    Artifact,
+    Capabilities,
+    ChatChoice,
+    ChatCompletionChunk,
+    ChatCompletionObject,
+    ChatMessage,
+    ClarkMetadata,
+    Cost,
+    MemoryList,
+    MemoryRecord,
+    ModelInfo,
+    ModelList,
+    ModelOption,
+    OutputMessage,
+    Pricing,
+    ResponseError,
+    ResponseEvent,
+    ResponseEventList,
+    ResponseObject,
+    ResponseStreamEvent,
+    Usage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ClarkClient",
+    "AsyncClarkClient",
+    "ClarkApiError",
+    "ModelInfo",
+    "ModelOption",
+    "ModelList",
+    "Pricing",
+    "Capabilities",
+    "ResponseObject",
+    "ResponseStreamEvent",
+    "ResponseEvent",
+    "ResponseEventList",
+    "OutputMessage",
+    "Artifact",
+    "ClarkMetadata",
+    "ResponseError",
+    "Cost",
+    "Usage",
+    "ChatCompletionObject",
+    "ChatCompletionChunk",
+    "ChatChoice",
+    "ChatMessage",
+    "MemoryRecord",
+    "MemoryList",
+]

clark_platform/_payloads.py

@@ -0,0 +1,123 @@
+"""Internal helpers for building request payloads.
+
+Shared by both the sync and async clients so the two stay in lockstep.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+DEFAULT_BASE_URL = "https://www.clarkchat.com"
+
+# Non-background responses/chat-completions calls can legitimately take up to
+# ~120s server-side (CLARK_PLATFORM_RESPONSE_WAIT_MS default), so the client
+# default timeout must comfortably exceed that.
+DEFAULT_TIMEOUT = 150.0
+
+ResponseInput = Union[str, List[Dict[str, Any]]]
+
+
+def omit_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def build_responses_payload(
+    *,
+    model: str,
+    input: ResponseInput,  # noqa: A002 - mirrors wire field name
+    tier_model_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    memory_scope: Optional[str] = None,
+    previous_response_id: Optional[str] = None,
+    background: Optional[bool] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    stream: Optional[bool] = None,
+) -> Dict[str, Any]:
+    return omit_none(
+        {
+            "model": model,
+            "tier_model_id": tier_model_id,
+            "input": input,
+            "conversation_id": conversation_id,
+            "memory_scope": memory_scope,
+            "previous_response_id": previous_response_id,
+            "background": background,
+            "metadata": metadata,
+            "stream": stream,
+        }
+    )
+
+
+def build_chat_completions_payload(
+    *,
+    model: str,
+    messages: List[Dict[str, Any]],
+    tier_model_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    memory_scope: Optional[str] = None,
+    previous_response_id: Optional[str] = None,
+    stream: Optional[bool] = None,
+    stream_options: Optional[Dict[str, Any]] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    tools: Optional[List[Dict[str, Any]]] = None,
+    tool_choice: Optional[Any] = None,
+    temperature: Optional[float] = None,
+    top_p: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    stop: Optional[Union[str, List[str]]] = None,
+    parallel_tool_calls: Optional[bool] = None,
+    reasoning_effort: Optional[str] = None,
+) -> Dict[str, Any]:
+    return omit_none(
+        {
+            "model": model,
+            "tier_model_id": tier_model_id,
+            "messages": messages,
+            "conversation_id": conversation_id,
+            "memory_scope": memory_scope,
+            "previous_response_id": previous_response_id,
+            "stream": stream,
+            "stream_options": stream_options,
+            "metadata": metadata,
+            "tools": tools,
+            "tool_choice": tool_choice,
+            "temperature": temperature,
+            "top_p": top_p,
+            "max_tokens": max_tokens,
+            "stop": stop,
+            "parallel_tool_calls": parallel_tool_calls,
+            "reasoning_effort": reasoning_effort,
+        }
+    )
+
+
+def build_events_params(
+    *,
+    after_seq: Optional[int] = None,
+    limit: Optional[int] = None,
+    types: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    params: Dict[str, Any] = {}
+    if after_seq is not None:
+        params["after_seq"] = after_seq
+    if limit is not None:
+        params["limit"] = limit
+    if types:
+        params["types"] = ",".join(types)
+    return params
+
+
+def build_memories_params(
+    *,
+    q: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    conversation_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    params: Dict[str, Any] = {}
+    if q is not None:
+        params["q"] = q
+    if tags:
+        params["tags"] = ",".join(tags)
+    if conversation_id is not None:
+        params["conversation_id"] = conversation_id
+    return params

clark_platform/async_client.py

@@ -0,0 +1,380 @@
+"""Asynchronous client for the Clark Platform API.
+
+Mirrors :mod:`clark_platform.client` method-for-method; see its docstrings
+for behavioral details not repeated here.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Dict, List, Optional, Union
+
+import httpx
+
+from ._payloads import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    ResponseInput,
+    build_chat_completions_payload,
+    build_events_params,
+    build_memories_params,
+    build_responses_payload,
+)
+from .errors import ClarkApiError
+from .models import (
+    ChatCompletionChunk,
+    ChatCompletionObject,
+    MemoryList,
+    ModelList,
+    ResponseEventList,
+    ResponseObject,
+    ResponseStreamEvent,
+)
+from .streaming import DONE_SENTINEL, aiter_sse_events
+
+
+class AsyncClarkClient:
+    """Async client for the Clark Platform API.
+
+    Example::
+
+        from clark_platform import AsyncClarkClient
+
+        async with AsyncClarkClient(api_key="clk_live_...") as client:
+            response = await client.responses.create(model="clark", input="hello")
+            print(response.output_text)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._owns_http_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+        self.models = AsyncModelsResource(self)
+        self.responses = AsyncResponsesResource(self)
+        self.chat = AsyncChatResource(self)
+        self.memories = AsyncMemoriesResource(self)
+
+    async def close(self) -> None:
+        if self._owns_http_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClarkClient":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.close()
+
+    # -- internal helpers ---------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    @staticmethod
+    def _error_from_response(response: httpx.Response) -> ClarkApiError:
+        try:
+            body = response.json()
+        except ValueError:
+            return ClarkApiError.from_unparsable_body(response.status_code, response.text)
+        return ClarkApiError.from_error_body(response.status_code, body)
+
+    async def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        response = await self._http.request(
+            method, self._url(path), params=params, json=json_body, headers=self._headers()
+        )
+        if response.status_code >= 400:
+            raise self._error_from_response(response)
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise ClarkApiError(
+                f"Failed to parse JSON response body: {exc}",
+                status_code=response.status_code,
+            ) from exc
+
+    async def stream_lines(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> AsyncIterator[str]:
+        async with self._http.stream(
+            method, self._url(path), json=json_body, headers=self._headers()
+        ) as response:
+            if response.status_code >= 400:
+                await response.aread()
+                raise self._error_from_response(response)
+            async for line in response.aiter_lines():
+                yield line
+
+
+class AsyncModelsResource:
+    def __init__(self, client: AsyncClarkClient) -> None:
+        self._client = client
+
+    async def list(self) -> ModelList:
+        body = await self._client.request_json("GET", "/v1/models")
+        return ModelList.from_dict(body)
+
+
+class AsyncResponsesResource:
+    def __init__(self, client: AsyncClarkClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        model: str,
+        input: ResponseInput,  # noqa: A002
+        tier_model_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        memory_scope: Optional[str] = None,
+        previous_response_id: Optional[str] = None,
+        background: Optional[bool] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> ResponseObject:
+        payload = build_responses_payload(
+            model=model,
+            input=input,
+            tier_model_id=tier_model_id,
+            conversation_id=conversation_id,
+            memory_scope=memory_scope,
+            previous_response_id=previous_response_id,
+            background=background,
+            metadata=metadata,
+            stream=False,
+        )
+        body = await self._client.request_json("POST", "/v1/responses", json_body=payload)
+        return ResponseObject.from_dict(body)
+
+    async def stream(
+        self,
+        *,
+        model: str,
+        input: ResponseInput,  # noqa: A002
+        tier_model_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        memory_scope: Optional[str] = None,
+        previous_response_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> AsyncIterator[ResponseStreamEvent]:
+        payload = build_responses_payload(
+            model=model,
+            input=input,
+            tier_model_id=tier_model_id,
+            conversation_id=conversation_id,
+            memory_scope=memory_scope,
+            previous_response_id=previous_response_id,
+            metadata=metadata,
+            stream=True,
+        )
+        lines = self._client.stream_lines("POST", "/v1/responses", json_body=payload)
+        async for event_name, data in aiter_sse_events(lines):
+            if data == DONE_SENTINEL:
+                return
+            obj = json.loads(data)
+            yield ResponseStreamEvent.from_dict(obj, event_name)
+
+    async def get(self, response_id: str) -> ResponseObject:
+        body = await self._client.request_json("GET", f"/v1/responses/{response_id}")
+        return ResponseObject.from_dict(body)
+
+    async def list_events(
+        self,
+        response_id: str,
+        *,
+        after_seq: Optional[int] = None,
+        limit: Optional[int] = None,
+        types: Optional[List[str]] = None,
+    ) -> ResponseEventList:
+        params = build_events_params(after_seq=after_seq, limit=limit, types=types)
+        body = await self._client.request_json(
+            "GET", f"/v1/responses/{response_id}/events", params=params
+        )
+        return ResponseEventList.from_dict(body)
+
+
+class AsyncChatCompletionsResource:
+    def __init__(self, client: AsyncClarkClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tier_model_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        memory_scope: Optional[str] = None,
+        previous_response_id: Optional[str] = None,
+        stream_options: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stop: Optional[Union[str, List[str]]] = None,
+    ) -> ChatCompletionObject:
+        payload = build_chat_completions_payload(
+            model=model,
+            messages=messages,
+            tier_model_id=tier_model_id,
+            conversation_id=conversation_id,
+            memory_scope=memory_scope,
+            previous_response_id=previous_response_id,
+            stream=False,
+            stream_options=stream_options,
+            metadata=metadata,
+            temperature=temperature,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            stop=stop,
+        )
+        body = await self._client.request_json("POST", "/v1/chat/completions", json_body=payload)
+        return ChatCompletionObject.from_dict(body)
+
+    async def stream(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tier_model_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        memory_scope: Optional[str] = None,
+        previous_response_id: Optional[str] = None,
+        stream_options: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stop: Optional[Union[str, List[str]]] = None,
+    ) -> AsyncIterator[ChatCompletionChunk]:
+        payload = build_chat_completions_payload(
+            model=model,
+            messages=messages,
+            tier_model_id=tier_model_id,
+            conversation_id=conversation_id,
+            memory_scope=memory_scope,
+            previous_response_id=previous_response_id,
+            stream=True,
+            stream_options=stream_options,
+            metadata=metadata,
+            temperature=temperature,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            stop=stop,
+        )
+        lines = self._client.stream_lines("POST", "/v1/chat/completions", json_body=payload)
+        async for _event_name, data in aiter_sse_events(lines):
+            if data == DONE_SENTINEL:
+                return
+            obj = json.loads(data)
+            yield ChatCompletionChunk.from_dict(obj)
+
+    async def create_passthrough(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Any] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stop: Optional[Union[str, List[str]]] = None,
+        parallel_tool_calls: Optional[bool] = None,
+        reasoning_effort: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        payload = build_chat_completions_payload(
+            model=model,
+            messages=messages,
+            stream=False,
+            tools=tools,
+            tool_choice=tool_choice,
+            temperature=temperature,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            stop=stop,
+            parallel_tool_calls=parallel_tool_calls,
+            reasoning_effort=reasoning_effort,
+            metadata=metadata,
+        )
+        return await self._client.request_json("POST", "/v1/chat/completions", json_body=payload)
+
+    async def stream_passthrough(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Any] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stop: Optional[Union[str, List[str]]] = None,
+        parallel_tool_calls: Optional[bool] = None,
+        reasoning_effort: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        payload = build_chat_completions_payload(
+            model=model,
+            messages=messages,
+            stream=True,
+            tools=tools,
+            tool_choice=tool_choice,
+            temperature=temperature,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            stop=stop,
+            parallel_tool_calls=parallel_tool_calls,
+            reasoning_effort=reasoning_effort,
+            metadata=metadata,
+        )
+        lines = self._client.stream_lines("POST", "/v1/chat/completions", json_body=payload)
+        async for _event_name, data in aiter_sse_events(lines):
+            if data == DONE_SENTINEL:
+                return
+            yield json.loads(data)
+
+
+class AsyncChatResource:
+    def __init__(self, client: AsyncClarkClient) -> None:
+        self.completions = AsyncChatCompletionsResource(client)
+
+
+class AsyncMemoriesResource:
+    def __init__(self, client: AsyncClarkClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        q: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        conversation_id: Optional[str] = None,
+    ) -> MemoryList:
+        params = build_memories_params(q=q, tags=tags, conversation_id=conversation_id)
+        body = await self._client.request_json("GET", "/v1/memories", params=params)
+        return MemoryList.from_dict(body)