clark-platform-client 0.1.0__tar.gz

clark_platform_client-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/

clark_platform_client-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: clark-platform-client
+Version: 0.1.0
+Summary: Typed sync/async Python client for the Clark Platform API
+Project-URL: Homepage, https://www.clarkchat.com
+Author: Clark Labs
+License: MIT
+Keywords: agent,api-client,clark,clark-labs,httpx
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clark-platform-client
+
+Typed, standalone Python client (sync + async) for the [Clark Platform
+API](https://www.clarkchat.com) — the OpenAI-compatible-ish public HTTP API
+for creating Clark agent runs, streaming their progress, and reading back
+chat-completion/response objects, usage, artifacts, and durable memory.
+
+This client implements the wire contract documented in
+[`platform/clients/API_CONTRACT.md`](../API_CONTRACT.md) in the Clark
+monorepo. If something here disagrees with that file, the contract file is
+the source of truth.
+
+- Only required dependency: [`httpx`](https://www.python-httpx.org/).
+- No `pydantic` — models are plain stdlib `dataclasses`.
+- Both a sync client (`ClarkClient`) and an async client (`AsyncClarkClient`);
+  pick one without pulling in `asyncio` machinery you don't need.
+- Python 3.9+.
+
+## Install
+
+Not published to PyPI yet. Install directly from a local checkout of this
+directory:
+
+```bash
+# with uv, inside another project
+uv add /path/to/clark/platform/clients/python
+
+# or with pip, editable install for local development
+pip install -e /path/to/clark/platform/clients/python
+```
+
+## Authentication
+
+Platform API keys (`clk_live_...`) are minted from the signed-in `/platform`
+page in the Clark web app — there is no public self-serve key-creation
+endpoint. Every key carries a fixed scope set
+(`responses:create`, `responses:read`, `models:read`, `artifacts:read`,
+`memories:read`).
+
+```python
+from clark_platform import ClarkClient
+
+client = ClarkClient(api_key="clk_live_xxxxxxxxxxxxxxxxxxxx")
+```
+
+By default the client talks to production (`https://www.clarkchat.com`).
+
+## Quickstart — sync
+
+```python
+from clark_platform import ClarkClient
+
+with ClarkClient(api_key="clk_live_...") as client:
+    models = client.models.list()
+    print([m.id for m in models.data])
+
+    response = client.responses.create(model="clark", input="Summarize this repo's README.")
+    print(response.status, response.output_text)
+
+    chat = client.chat.completions.create(
+        model="openrouter:qwen35_flash",
+        messages=[{"role": "user", "content": "hello"}],
+    )
+    print(chat.output_text)
+```
+
+## Quickstart — async
+
+```python
+import asyncio
+from clark_platform import AsyncClarkClient
+
+
+async def main() -> None:
+    async with AsyncClarkClient(api_key="clk_live_...") as client:
+        response = await client.responses.create(model="clark", input="hello")
+        print(response.output_text)
+
+
+asyncio.run(main())
+```
+
+## Two families of tier: agentic vs. `clark-code` passthrough
+
+The API has two entirely different behaviors depending on `model`:
+
+1. **Agentic tiers** (`clark`, `clark_max`, `openrouter:*`) — Clark runs its
+   own internal agent loop and returns only the final projected answer.
+   `tools`/`tool_choice` are not accepted by these methods (the server
+   rejects them with `400 unsupported_parameter`, so the SDK doesn't even
+   expose those parameters on `responses.create`/`chat.completions.create`).
+2. **The `clark-code` passthrough tier** — your `messages` (including prior
+   `tool_calls`/`tool` messages) are forwarded verbatim to the underlying
+   OpenRouter-compatible model, and native OpenAI-format `tool_calls` come
+   back for you to execute yourself. Clark does not run tools for this tier.
+   This is **only** available via `/v1/chat/completions`, never
+   `/v1/responses`.
+
+Because these are different response *shapes*, the passthrough tier is
+exposed via clearly separate methods that return the raw upstream JSON dict
+instead of a typed Clark object:
+
+```python
+# Agentic — typed ChatCompletionObject, no tools allowed.
+chat = client.chat.completions.create(model="clark", messages=[...])
+
+# Passthrough — raw OpenAI-compatible dict, tools/tool_choice forwarded verbatim.
+raw = client.chat.completions.create_passthrough(
+    model="clark-code",
+    messages=[...],
+    tools=[{"type": "function", "function": {...}}],
+)
+```
+
+## Streaming
+
+### `responses.stream(...)`
+
+Named SSE events (`response.created`, `response.output_text.delta`,
+`response.artifact.completed`, `response.usage.updated`,
+`response.completed`/`response.failed`, ...). Per the contract, the full
+answer arrives as a **single** `response.output_text.delta` event, not
+token-by-token — the iterator API is for symmetry with chat-completions
+streaming and future finer-grained deltas.
+
+```python
+for event in client.responses.stream(model="clark", input="hello"):
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="")
+    elif event.type == "response.completed":
+        print("\n--- done ---", event.response.status)
+```
+
+Async:
+
+```python
+async for event in async_client.responses.stream(model="clark", input="hello"):
+    ...
+```
+
+### `chat.completions.stream(...)`
+
+Plain `data:`-only SSE (no `event:` name), `chat.completion.chunk` objects,
+terminated by the server's literal `data: [DONE]` (already consumed for you
+— it never appears as a yielded item):
+
+```python
+for chunk in client.chat.completions.stream(
+    model="clark",
+    messages=[{"role": "user", "content": "hello"}],
+    stream_options={"include_usage": True},
+):
+    for choice in chunk.choices:
+        if choice.delta.content:
+            print(choice.delta.content, end="")
+    if chunk.usage:
+        print("\nusage:", chunk.usage)
+```
+
+### `chat.completions.stream_passthrough(...)`
+
+Same framing, but yields raw upstream JSON dicts (native `tool_calls`
+deltas and all) instead of a typed `ChatCompletionChunk`, since the
+passthrough tier's chunk shape is whatever the upstream OpenAI-compatible
+provider sends.
+
+## Other endpoints
+
+```python
+# Poll a response (e.g. after background=True, or to recover from a chat
+# completions timeout by replacing the "chatcmpl_" prefix with "resp_").
+response = client.responses.get("resp_01jz4n8h2f7g9k4q2m6s")
+
+# Progress events for a response.
+events = client.responses.list_events("resp_01jz4n8h2f7g9k4q2m6s", after_seq=0, limit=200)
+
+# Durable memory.
+memories = client.memories.list(q="deploy checklist")
+```
+
+## Errors
+
+All non-2xx responses raise `ClarkApiError`, parsed from the API's error
+envelope:
+
+```python
+from clark_platform import ClarkApiError
+
+try:
+    client.responses.create(model="clark", input="hello")
+except ClarkApiError as err:
+    print(err.status_code, err.type, err.code, err.param, err.message)
+```
+
+Network-level failures (connection errors, timeouts, DNS failures) are
+**not** wrapped — they surface as the underlying `httpx` exception (e.g.
+`httpx.ConnectError`, `httpx.TimeoutException`), so you can rely on
+`httpx`'s own exception hierarchy for those.
+
+## Timeouts
+
+Non-background `responses`/`chat.completions` calls can legitimately take up
+to ~120s server-side (`CLARK_PLATFORM_RESPONSE_WAIT_MS`, default 120000ms).
+The client defaults its `httpx` timeout to 150s to comfortably clear that;
+pass your own `timeout=` (or a pre-configured `http_client=`) to
+`ClarkClient`/`AsyncClarkClient` to change it.
+
+## Development
+
+```bash
+cd platform/clients/python
+uv sync --python 3.12
+uv run --python 3.12 pytest -q
+```
+
+`examples/live_smoke.py` is an opt-in, real-network smoke test — it reads
+`CLARK_API_BASE_URL`, `CLARK_API_KEY`, and `CLARK_TEST_MODEL` from the
+environment and exits early with a clear message if `CLARK_API_KEY` is
+unset. It is not part of the test suite and is never run automatically.

clark_platform_client-0.1.0/README.md

@@ -0,0 +1,219 @@
+# clark-platform-client
+
+Typed, standalone Python client (sync + async) for the [Clark Platform
+API](https://www.clarkchat.com) — the OpenAI-compatible-ish public HTTP API
+for creating Clark agent runs, streaming their progress, and reading back
+chat-completion/response objects, usage, artifacts, and durable memory.
+
+This client implements the wire contract documented in
+[`platform/clients/API_CONTRACT.md`](../API_CONTRACT.md) in the Clark
+monorepo. If something here disagrees with that file, the contract file is
+the source of truth.
+
+- Only required dependency: [`httpx`](https://www.python-httpx.org/).
+- No `pydantic` — models are plain stdlib `dataclasses`.
+- Both a sync client (`ClarkClient`) and an async client (`AsyncClarkClient`);
+  pick one without pulling in `asyncio` machinery you don't need.
+- Python 3.9+.
+
+## Install
+
+Not published to PyPI yet. Install directly from a local checkout of this
+directory:
+
+```bash
+# with uv, inside another project
+uv add /path/to/clark/platform/clients/python
+
+# or with pip, editable install for local development
+pip install -e /path/to/clark/platform/clients/python
+```
+
+## Authentication
+
+Platform API keys (`clk_live_...`) are minted from the signed-in `/platform`
+page in the Clark web app — there is no public self-serve key-creation
+endpoint. Every key carries a fixed scope set
+(`responses:create`, `responses:read`, `models:read`, `artifacts:read`,
+`memories:read`).
+
+```python
+from clark_platform import ClarkClient
+
+client = ClarkClient(api_key="clk_live_xxxxxxxxxxxxxxxxxxxx")
+```
+
+By default the client talks to production (`https://www.clarkchat.com`).
+
+## Quickstart — sync
+
+```python
+from clark_platform import ClarkClient
+
+with ClarkClient(api_key="clk_live_...") as client:
+    models = client.models.list()
+    print([m.id for m in models.data])
+
+    response = client.responses.create(model="clark", input="Summarize this repo's README.")
+    print(response.status, response.output_text)
+
+    chat = client.chat.completions.create(
+        model="openrouter:qwen35_flash",
+        messages=[{"role": "user", "content": "hello"}],
+    )
+    print(chat.output_text)
+```
+
+## Quickstart — async
+
+```python
+import asyncio
+from clark_platform import AsyncClarkClient
+
+
+async def main() -> None:
+    async with AsyncClarkClient(api_key="clk_live_...") as client:
+        response = await client.responses.create(model="clark", input="hello")
+        print(response.output_text)
+
+
+asyncio.run(main())
+```
+
+## Two families of tier: agentic vs. `clark-code` passthrough
+
+The API has two entirely different behaviors depending on `model`:
+
+1. **Agentic tiers** (`clark`, `clark_max`, `openrouter:*`) — Clark runs its
+   own internal agent loop and returns only the final projected answer.
+   `tools`/`tool_choice` are not accepted by these methods (the server
+   rejects them with `400 unsupported_parameter`, so the SDK doesn't even
+   expose those parameters on `responses.create`/`chat.completions.create`).
+2. **The `clark-code` passthrough tier** — your `messages` (including prior
+   `tool_calls`/`tool` messages) are forwarded verbatim to the underlying
+   OpenRouter-compatible model, and native OpenAI-format `tool_calls` come
+   back for you to execute yourself. Clark does not run tools for this tier.
+   This is **only** available via `/v1/chat/completions`, never
+   `/v1/responses`.
+
+Because these are different response *shapes*, the passthrough tier is
+exposed via clearly separate methods that return the raw upstream JSON dict
+instead of a typed Clark object:
+
+```python
+# Agentic — typed ChatCompletionObject, no tools allowed.
+chat = client.chat.completions.create(model="clark", messages=[...])
+
+# Passthrough — raw OpenAI-compatible dict, tools/tool_choice forwarded verbatim.
+raw = client.chat.completions.create_passthrough(
+    model="clark-code",
+    messages=[...],
+    tools=[{"type": "function", "function": {...}}],
+)
+```
+
+## Streaming
+
+### `responses.stream(...)`
+
+Named SSE events (`response.created`, `response.output_text.delta`,
+`response.artifact.completed`, `response.usage.updated`,
+`response.completed`/`response.failed`, ...). Per the contract, the full
+answer arrives as a **single** `response.output_text.delta` event, not
+token-by-token — the iterator API is for symmetry with chat-completions
+streaming and future finer-grained deltas.
+
+```python
+for event in client.responses.stream(model="clark", input="hello"):
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="")
+    elif event.type == "response.completed":
+        print("\n--- done ---", event.response.status)
+```
+
+Async:
+
+```python
+async for event in async_client.responses.stream(model="clark", input="hello"):
+    ...
+```
+
+### `chat.completions.stream(...)`
+
+Plain `data:`-only SSE (no `event:` name), `chat.completion.chunk` objects,
+terminated by the server's literal `data: [DONE]` (already consumed for you
+— it never appears as a yielded item):
+
+```python
+for chunk in client.chat.completions.stream(
+    model="clark",
+    messages=[{"role": "user", "content": "hello"}],
+    stream_options={"include_usage": True},
+):
+    for choice in chunk.choices:
+        if choice.delta.content:
+            print(choice.delta.content, end="")
+    if chunk.usage:
+        print("\nusage:", chunk.usage)
+```
+
+### `chat.completions.stream_passthrough(...)`
+
+Same framing, but yields raw upstream JSON dicts (native `tool_calls`
+deltas and all) instead of a typed `ChatCompletionChunk`, since the
+passthrough tier's chunk shape is whatever the upstream OpenAI-compatible
+provider sends.
+
+## Other endpoints
+
+```python
+# Poll a response (e.g. after background=True, or to recover from a chat
+# completions timeout by replacing the "chatcmpl_" prefix with "resp_").
+response = client.responses.get("resp_01jz4n8h2f7g9k4q2m6s")
+
+# Progress events for a response.
+events = client.responses.list_events("resp_01jz4n8h2f7g9k4q2m6s", after_seq=0, limit=200)
+
+# Durable memory.
+memories = client.memories.list(q="deploy checklist")
+```
+
+## Errors
+
+All non-2xx responses raise `ClarkApiError`, parsed from the API's error
+envelope:
+
+```python
+from clark_platform import ClarkApiError
+
+try:
+    client.responses.create(model="clark", input="hello")
+except ClarkApiError as err:
+    print(err.status_code, err.type, err.code, err.param, err.message)
+```
+
+Network-level failures (connection errors, timeouts, DNS failures) are
+**not** wrapped — they surface as the underlying `httpx` exception (e.g.
+`httpx.ConnectError`, `httpx.TimeoutException`), so you can rely on
+`httpx`'s own exception hierarchy for those.
+
+## Timeouts
+
+Non-background `responses`/`chat.completions` calls can legitimately take up
+to ~120s server-side (`CLARK_PLATFORM_RESPONSE_WAIT_MS`, default 120000ms).
+The client defaults its `httpx` timeout to 150s to comfortably clear that;
+pass your own `timeout=` (or a pre-configured `http_client=`) to
+`ClarkClient`/`AsyncClarkClient` to change it.
+
+## Development
+
+```bash
+cd platform/clients/python
+uv sync --python 3.12
+uv run --python 3.12 pytest -q
+```
+
+`examples/live_smoke.py` is an opt-in, real-network smoke test — it reads
+`CLARK_API_BASE_URL`, `CLARK_API_KEY`, and `CLARK_TEST_MODEL` from the
+environment and exits early with a clear message if `CLARK_API_KEY` is
+unset. It is not part of the test suite and is never run automatically.

clark_platform_client-0.1.0/examples/live_smoke.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Opt-in real-network smoke test for the Clark Platform API client.
+
+This is NOT part of the automated test suite (it is never imported or run by
+pytest) and is never invoked automatically. It exists so a human can sanity
+check the client against a live Clark deployment.
+
+Usage:
+
+    export CLARK_API_BASE_URL="https://www.clarkchat.com"   # or prod default
+    export CLARK_API_KEY="clk_live_xxxxxxxxxxxxxxxxxxxx"
+    export CLARK_TEST_MODEL="openrouter:qwen35_flash"        # optional
+    python examples/live_smoke.py
+
+If ``CLARK_API_KEY`` is unset, this script prints a clear message and exits
+without making any network calls.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from clark_platform import ClarkApiError, ClarkClient
+
+
+def main() -> int:
+    api_key = os.environ.get("CLARK_API_KEY")
+    if not api_key:
+        print(
+            "CLARK_API_KEY is not set -- skipping live smoke test.\n"
+            "Set CLARK_API_KEY (and optionally CLARK_API_BASE_URL, CLARK_TEST_MODEL) "
+            "to run this against a real Clark deployment.",
+            file=sys.stderr,
+        )
+        return 0
+
+    base_url = os.environ.get("CLARK_API_BASE_URL", "https://www.clarkchat.com")
+    model = os.environ.get("CLARK_TEST_MODEL", "openrouter:qwen35_flash")
+
+    with ClarkClient(api_key=api_key, base_url=base_url) as client:
+        print(f"Listing models from {base_url} ...")
+        models = client.models.list()
+        for m in models.data:
+            print(f"  - {m.id} ({m.label})")
+
+        print(f"\nRunning a trivial non-streaming chat completion with model={model!r} ...")
+        try:
+            completion = client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": "Reply with exactly the word: pong"}],
+            )
+        except ClarkApiError as err:
+            print(f"Chat completion failed: {err.status_code} {err.type}: {err.message}", file=sys.stderr)
+            return 1
+
+        print("Response:")
+        print(f"  id: {completion.id}")
+        print(f"  finish_reason: {completion.choices[0].finish_reason if completion.choices else None}")
+        print(f"  content: {completion.output_text!r}")
+        if completion.usage:
+            print(f"  usage: {completion.usage}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clark_platform_client-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "clark-platform-client"
+version = "0.1.0"
+description = "Typed sync/async Python client for the Clark Platform API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Clark Labs" }]
+keywords = ["clark", "clark-labs", "api-client", "agent", "httpx"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://www.clarkchat.com"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clark_platform"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = ["pytest>=7.4", "pytest-asyncio>=0.21"]

clark_platform_client-0.1.0/src/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",
+]