clone-sdk 0.2.0__tar.gz

clone_sdk-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+artifacts/
+test-results/
+playwright-report/
+release-manifest.json
+*.tgz
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store
+
+# Local audit and agent output must never enter the public repository.
+.gstack/
+output/
+coverage/
+python/.venv/
+python/dist/
+python/.pytest_cache/
+python/.ruff_cache/
+__pycache__/
+*.pyc

clone_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clone contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clone_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: clone-sdk
+Version: 0.2.0
+Summary: Server-side Python client for Clone prompt predictions.
+Project-URL: Homepage, https://clone.is/clone-sdk
+Project-URL: Repository, https://github.com/cloneisyou/clone-sdk
+Project-URL: Documentation, https://clone.is/docs
+Project-URL: Issues, https://github.com/cloneisyou/clone-sdk/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic<3,>=2.7
+Description-Content-Type: text/markdown
+
+# Clone Python SDK
+
+Server-side synchronous and asynchronous clients for Clone predictions, usage,
+observation events, cancellation and optional user-approved Clone connections.
+Composer UI stays in the JavaScript SDK. This client never submits a user message.
+
+Python 3.11+. The candidate distribution is `clone-sdk`; import `clone_sdk`.
+Until the first PyPI publication, install the verified wheel from the release.
+
+```sh
+pip install ./clone_sdk-0.2.0-py3-none-any.whl
+```
+
+```python
+import os
+from clone_sdk import CloneClient
+
+with CloneClient(os.environ["CLONE_APP_KEY"]) as client:
+    result = client.predict(
+        "subject-from-your-authenticated-session",
+        {
+            "request_id": "prediction-001",
+            "session_id": "conversation-001",
+            "context_revision": "1",
+            "mode": "next_prompt",
+            "draft": {"text": "", "revision": 0},
+            "messages": [{"role": "user", "content": "Draft a product announcement.", "origin": "human"}],
+            "language": "en",
+        },
+    )
+    print(result.status)
+```
+
+For FastAPI or other async servers, use `async with AsyncCloneClient(...)` and
+`await client.predict(...)`. Reuse a client for the application's lifetime and
+close it during shutdown. The async client enforces a total 15-second deadline,
+including body reads. The sync client uses 15-second per-I/O timeouts and checks
+the elapsed budget between response chunks. Both bound concurrency to 16 by
+default, reject saturation without queuing, limit response bodies to 1 MiB, and
+never automatically retry potentially billable work. Override `timeout` up to
+30 seconds and `max_concurrent_requests` up to 1,000 after measuring your load.
+
+Derive `user_id` from your server session; the client overwrites an untrusted
+body's `user_id`. Keep the app key exclusively on your backend. HTTPS is required
+except loopback development. Redirects are not followed. Client errors expose
+only a safe `code`, HTTP `status` and numeric `retry_after`, never response text.
+
+Keep the same request ID and exact body when reconciling an unknown result.
+Hide failed predictions and keep your editor and manual send path independent.
+Response identity is checked; the host still owns expiry, rendering, Tab/Undo,
+session changes and successful-send acknowledgments.
+
+Optional personalization uses `started, flow = client.connect(user_id, redirect_uri)`
+to create a PKCE flow (or `started, flow = await client.connect(...)` for async).
+Store the returned flow in a server session, redirect the user to
+`started.authorize_url`, then call `exchange(flow, callback, authenticated_user_id)`.
+State, request and subject must match. The flow contains a secret verifier and
+must not be logged or serialized to browser storage. Basic predictions need no
+Clone end-user account.
+
+```python
+client.record_event(
+    subject,
+    {
+        "event_id": "event-001",
+        "request_id": "prediction-001",
+        "kind": "presented",
+    },
+)
+usage = client.usage()
+client.cancel(subject, "prediction-001")
+```
+
+Only report `submitted` after your host accepts the send. Reuse an event ID on
+delivery retries. Events contain no prompt text and do not change billing.
+Read the [public API](https://clone.is/docs/api-reference),
+[billing](https://clone.is/docs/billing) and
+[reliability](https://clone.is/docs/reliability) contracts before production use.
+
+Development: `uv sync`, `uv run pytest`, `uv run ruff check .`, `uv build` and
+`uv run twine check dist/*`. All ordinary tests use local or mocked transports;
+they do not establish model quality or customer adoption.

clone_sdk-0.2.0/README.md

@@ -0,0 +1,82 @@
+# Clone Python SDK
+
+Server-side synchronous and asynchronous clients for Clone predictions, usage,
+observation events, cancellation and optional user-approved Clone connections.
+Composer UI stays in the JavaScript SDK. This client never submits a user message.
+
+Python 3.11+. The candidate distribution is `clone-sdk`; import `clone_sdk`.
+Until the first PyPI publication, install the verified wheel from the release.
+
+```sh
+pip install ./clone_sdk-0.2.0-py3-none-any.whl
+```
+
+```python
+import os
+from clone_sdk import CloneClient
+
+with CloneClient(os.environ["CLONE_APP_KEY"]) as client:
+    result = client.predict(
+        "subject-from-your-authenticated-session",
+        {
+            "request_id": "prediction-001",
+            "session_id": "conversation-001",
+            "context_revision": "1",
+            "mode": "next_prompt",
+            "draft": {"text": "", "revision": 0},
+            "messages": [{"role": "user", "content": "Draft a product announcement.", "origin": "human"}],
+            "language": "en",
+        },
+    )
+    print(result.status)
+```
+
+For FastAPI or other async servers, use `async with AsyncCloneClient(...)` and
+`await client.predict(...)`. Reuse a client for the application's lifetime and
+close it during shutdown. The async client enforces a total 15-second deadline,
+including body reads. The sync client uses 15-second per-I/O timeouts and checks
+the elapsed budget between response chunks. Both bound concurrency to 16 by
+default, reject saturation without queuing, limit response bodies to 1 MiB, and
+never automatically retry potentially billable work. Override `timeout` up to
+30 seconds and `max_concurrent_requests` up to 1,000 after measuring your load.
+
+Derive `user_id` from your server session; the client overwrites an untrusted
+body's `user_id`. Keep the app key exclusively on your backend. HTTPS is required
+except loopback development. Redirects are not followed. Client errors expose
+only a safe `code`, HTTP `status` and numeric `retry_after`, never response text.
+
+Keep the same request ID and exact body when reconciling an unknown result.
+Hide failed predictions and keep your editor and manual send path independent.
+Response identity is checked; the host still owns expiry, rendering, Tab/Undo,
+session changes and successful-send acknowledgments.
+
+Optional personalization uses `started, flow = client.connect(user_id, redirect_uri)`
+to create a PKCE flow (or `started, flow = await client.connect(...)` for async).
+Store the returned flow in a server session, redirect the user to
+`started.authorize_url`, then call `exchange(flow, callback, authenticated_user_id)`.
+State, request and subject must match. The flow contains a secret verifier and
+must not be logged or serialized to browser storage. Basic predictions need no
+Clone end-user account.
+
+```python
+client.record_event(
+    subject,
+    {
+        "event_id": "event-001",
+        "request_id": "prediction-001",
+        "kind": "presented",
+    },
+)
+usage = client.usage()
+client.cancel(subject, "prediction-001")
+```
+
+Only report `submitted` after your host accepts the send. Reuse an event ID on
+delivery retries. Events contain no prompt text and do not change billing.
+Read the [public API](https://clone.is/docs/api-reference),
+[billing](https://clone.is/docs/billing) and
+[reliability](https://clone.is/docs/reliability) contracts before production use.
+
+Development: `uv sync`, `uv run pytest`, `uv run ruff check .`, `uv build` and
+`uv run twine check dist/*`. All ordinary tests use local or mocked transports;
+they do not establish model quality or customer adoption.

clone_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling==1.31.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clone-sdk"
+version = "0.2.0"
+description = "Server-side Python client for Clone prompt predictions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.28.1,<1", "pydantic>=2.7,<3"]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed"]
+
+[project.urls]
+Homepage = "https://clone.is/clone-sdk"
+Repository = "https://github.com/cloneisyou/clone-sdk"
+Documentation = "https://clone.is/docs"
+Issues = "https://github.com/cloneisyou/clone-sdk/issues"
+
+[dependency-groups]
+dev = ["pytest>=8.3,<10", "pytest-asyncio>=0.25,<2", "ruff>=0.9,<1", "build>=1.2,<2", "twine>=6,<7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clone_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

clone_sdk-0.2.0/src/clone_sdk/__init__.py

@@ -0,0 +1,27 @@
+from .client import AsyncCloneClient, CloneClient, CloneError, ConnectionFlow
+from .models import (
+    CancelResult,
+    Connection,
+    ConnectionStarted,
+    EventResult,
+    FeedbackCleared,
+    Prediction,
+    RevokeResult,
+    Usage,
+)
+
+__all__ = [
+    "AsyncCloneClient",
+    "CloneClient",
+    "CloneError",
+    "ConnectionFlow",
+    "CancelResult",
+    "Connection",
+    "ConnectionStarted",
+    "EventResult",
+    "FeedbackCleared",
+    "Prediction",
+    "RevokeResult",
+    "Usage",
+]
+__version__ = "0.2.0"

clone_sdk-0.2.0/src/clone_sdk/client.py

@@ -0,0 +1,325 @@
+"""Bounded clients. No automatic retries of potentially billable requests."""
+
+import asyncio
+import base64
+import hashlib
+import math
+import re
+import secrets
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, TypeVar
+from urllib.parse import quote, urlsplit
+
+import httpx
+from pydantic import ValidationError
+
+from .models import (
+    CancelResult,
+    Connection,
+    ConnectionStarted,
+    EventResult,
+    FeedbackCleared,
+    Prediction,
+    ResponseModel,
+    RevokeResult,
+    Usage,
+)
+
+T = TypeVar("T", bound=ResponseModel)
+MAX_RESPONSE_BYTES = 1_048_576
+
+
+class CloneError(Exception):
+    """Safe code and status only. Never contains response text, prompts or credentials."""
+
+    def __init__(self, code: str, status: int = 0, retry_after: float | None = None):
+        self.code, self.status, self.retry_after = code, status, retry_after
+        super().__init__(code)
+
+
+@dataclass(frozen=True, repr=False)
+class ConnectionFlow:
+    request_id: str
+    state: str
+    code_verifier: str
+    redirect_uri: str
+    user_id: str
+
+
+def _decode(response: httpx.Response, data: bytes, model: type[T]) -> T:
+    import json
+
+    try:
+        body = json.loads(data)
+    except (ValueError, UnicodeError):
+        body = None
+    if not response.is_success:
+        detail = body.get("detail") if isinstance(body, dict) else None
+        code = detail.get("code") if isinstance(detail, dict) else None
+        code = (
+            code
+            if isinstance(code, str) and re.fullmatch(r"[a-z][a-z0-9_]{0,127}", code)
+            else "request_failed"
+        )
+        try:
+            retry_after = float(response.headers["Retry-After"])
+            if not math.isfinite(retry_after) or retry_after < 0:
+                retry_after = None
+        except (KeyError, ValueError):
+            retry_after = None
+        raise CloneError(code, response.status_code, retry_after)
+    try:
+        return model.model_validate(body)
+    except ValidationError:
+        raise CloneError("invalid_response", 502) from None
+
+
+def _identity(result: Prediction, request: Mapping[str, Any]) -> Prediction:
+    draft = request.get("draft", {})
+    expected = (
+        request.get("request_id"),
+        request.get("session_id"),
+        request.get("connection_id"),
+        draft.get("revision"),
+        request.get("context_revision"),
+    )
+    actual = (
+        result.request_id,
+        result.session_id,
+        result.connection_id,
+        result.draft_revision,
+        result.context_revision,
+    )
+    if expected != actual:
+        raise CloneError("response_identity_mismatch", 502)
+    if result.status == "abstained" and (result.completion or result.usage.prediction_units):
+        raise CloneError("invalid_response", 502)
+    return result
+
+
+class _Options:
+    def __init__(self, api_key: str, base_url: str, timeout: float, max_concurrent_requests: int):
+        url = urlsplit(base_url)
+        if url.scheme != "https" and not (
+            url.scheme == "http" and url.hostname in {"localhost", "127.0.0.1", "::1"}
+        ):
+            raise ValueError("Clone API requires HTTPS; loopback HTTP is for development only")
+        if not url.hostname or url.username or url.password or url.query or url.fragment:
+            raise ValueError("Invalid Clone API URL")
+        if not isinstance(api_key, str) or not api_key.startswith("clnp_"):
+            raise ValueError("An app-scoped Clone API key is required")
+        if isinstance(timeout, bool) or not math.isfinite(timeout) or not 0 < timeout <= 30:
+            raise ValueError("timeout must be greater than zero and at most 30 seconds")
+        if type(max_concurrent_requests) is not int or not 1 <= max_concurrent_requests <= 1000:
+            raise ValueError("max_concurrent_requests must be between 1 and 1000")
+        self.base_url, self.timeout, self.limit = base_url.rstrip("/"), timeout, max_concurrent_requests
+        self.headers = {"Authorization": "Bearer " + api_key}
+
+    @staticmethod
+    def start_flow(user_id: str, redirect_uri: str):
+        verifier, state = secrets.token_urlsafe(48), secrets.token_urlsafe(48)
+        challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=")
+        return (
+            verifier,
+            state,
+            {"user_id": user_id, "redirect_uri": redirect_uri, "state": state, "code_challenge": challenge},
+        )
+
+    @staticmethod
+    def exchange_body(flow: ConnectionFlow, callback: Mapping[str, str], user_id: str):
+        if (
+            flow.user_id != user_id
+            or callback.get("state") != flow.state
+            or callback.get("request_id") != flow.request_id
+            or not callback.get("code")
+        ):
+            raise CloneError("invalid_connect_callback", 400)
+        return {
+            "request_id": flow.request_id,
+            "user_id": user_id,
+            "redirect_uri": flow.redirect_uri,
+            "code_verifier": flow.code_verifier,
+            "code": callback["code"],
+        }
+
+
+class CloneClient(_Options):
+    """Synchronous client with connection reuse, per-I/O timeouts and fail-fast concurrency."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.clone.is",
+        timeout: float = 15,
+        max_concurrent_requests: int = 16,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        super().__init__(api_key, base_url, timeout, max_concurrent_requests)
+        self._slots = threading.BoundedSemaphore(self.limit)
+        self._client = httpx.Client(
+            timeout=timeout,
+            follow_redirects=False,
+            trust_env=False,
+            transport=transport,
+            limits=httpx.Limits(max_connections=self.limit, max_keepalive_connections=self.limit),
+        )
+
+    def _call(self, path: str, model: type[T], body: dict | None = None) -> T:
+        if not self._slots.acquire(blocking=False):
+            raise CloneError("client_capacity_exceeded", 503)
+        try:
+            start = time.monotonic()
+            with self._client.stream(
+                "GET" if body is None else "POST",
+                self.base_url + "/v1" + path,
+                headers=self.headers,
+                json=body,
+            ) as response:
+                data = bytearray()
+                for chunk in response.iter_bytes():
+                    if time.monotonic() - start > self.timeout:
+                        raise CloneError("request_timeout", 504)
+                    data.extend(chunk)
+                    if len(data) > MAX_RESPONSE_BYTES:
+                        raise CloneError("response_too_large", 502)
+                return _decode(response, bytes(data), model)
+        except httpx.TimeoutException:
+            raise CloneError("request_timeout", 504) from None
+        except httpx.HTTPError:
+            raise CloneError("network_error") from None
+        finally:
+            self._slots.release()
+
+    def predict(self, user_id: str, request: Mapping[str, Any]) -> Prediction:
+        return _identity(self._call("/predictions", Prediction, {**request, "user_id": user_id}), request)
+
+    def record_event(self, user_id: str, event: Mapping[str, Any]) -> EventResult:
+        return self._call("/prediction-events", EventResult, {**event, "user_id": user_id})
+
+    def clear_feedback(self, user_id: str) -> FeedbackCleared:
+        return self._call("/prediction-feedback/clear", FeedbackCleared, {"user_id": user_id})
+
+    def cancel(self, user_id: str, request_id: str) -> CancelResult:
+        return self._call(
+            f"/predictions/{quote(request_id, safe='')}/cancel", CancelResult, {"user_id": user_id}
+        )
+
+    def usage(self) -> Usage:
+        return self._call("/usage", Usage)
+
+    def revoke(self, user_id: str, connection_id: str) -> RevokeResult:
+        return self._call(
+            f"/connections/{quote(connection_id, safe='')}/revoke", RevokeResult, {"user_id": user_id}
+        )
+
+    def connect(self, user_id: str, redirect_uri: str) -> tuple[ConnectionStarted, ConnectionFlow]:
+        verifier, state, body = self.start_flow(user_id, redirect_uri)
+        result = self._call("/connections", ConnectionStarted, body)
+        return result, ConnectionFlow(result.request_id, state, verifier, redirect_uri, user_id)
+
+    def exchange(self, flow: ConnectionFlow, callback: Mapping[str, str], user_id: str) -> Connection:
+        return self._call("/connections/exchange", Connection, self.exchange_body(flow, callback, user_id))
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+class AsyncCloneClient(_Options):
+    """Async client with a total deadline including response-body reads, without automatic retries."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.clone.is",
+        timeout: float = 15,
+        max_concurrent_requests: int = 16,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        super().__init__(api_key, base_url, timeout, max_concurrent_requests)
+        self._in_flight = 0
+        self._client = httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=False,
+            trust_env=False,
+            transport=transport,
+            limits=httpx.Limits(max_connections=self.limit, max_keepalive_connections=self.limit),
+        )
+
+    async def _call(self, path: str, model: type[T], body: dict | None = None) -> T:
+        if self._in_flight >= self.limit:
+            raise CloneError("client_capacity_exceeded", 503)
+        self._in_flight += 1
+        try:
+            async with asyncio.timeout(self.timeout):
+                async with self._client.stream(
+                    "GET" if body is None else "POST",
+                    self.base_url + "/v1" + path,
+                    headers=self.headers,
+                    json=body,
+                ) as response:
+                    data = bytearray()
+                    async for chunk in response.aiter_bytes():
+                        data.extend(chunk)
+                        if len(data) > MAX_RESPONSE_BYTES:
+                            raise CloneError("response_too_large", 502)
+                    return _decode(response, bytes(data), model)
+        except (TimeoutError, httpx.TimeoutException):
+            raise CloneError("request_timeout", 504) from None
+        except httpx.HTTPError:
+            raise CloneError("network_error") from None
+        finally:
+            self._in_flight -= 1
+
+    async def predict(self, user_id: str, request: Mapping[str, Any]) -> Prediction:
+        return _identity(
+            await self._call("/predictions", Prediction, {**request, "user_id": user_id}), request
+        )
+
+    async def record_event(self, user_id: str, event: Mapping[str, Any]) -> EventResult:
+        return await self._call("/prediction-events", EventResult, {**event, "user_id": user_id})
+
+    async def clear_feedback(self, user_id: str) -> FeedbackCleared:
+        return await self._call("/prediction-feedback/clear", FeedbackCleared, {"user_id": user_id})
+
+    async def cancel(self, user_id: str, request_id: str) -> CancelResult:
+        return await self._call(
+            f"/predictions/{quote(request_id, safe='')}/cancel", CancelResult, {"user_id": user_id}
+        )
+
+    async def usage(self) -> Usage:
+        return await self._call("/usage", Usage)
+
+    async def revoke(self, user_id: str, connection_id: str) -> RevokeResult:
+        return await self._call(
+            f"/connections/{quote(connection_id, safe='')}/revoke", RevokeResult, {"user_id": user_id}
+        )
+
+    async def connect(self, user_id: str, redirect_uri: str) -> tuple[ConnectionStarted, ConnectionFlow]:
+        verifier, state, body = self.start_flow(user_id, redirect_uri)
+        result = await self._call("/connections", ConnectionStarted, body)
+        return result, ConnectionFlow(result.request_id, state, verifier, redirect_uri, user_id)
+
+    async def exchange(self, flow: ConnectionFlow, callback: Mapping[str, str], user_id: str) -> Connection:
+        return await self._call(
+            "/connections/exchange", Connection, self.exchange_body(flow, callback, user_id)
+        )
+
+    async def close(self):
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.close()