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.

pip install ./clone_sdk-0.2.0-py3-none-any.whl

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.

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, billing and 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.