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.
