humansand 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ .venv/
2
+ __pycache__/
3
+ .env
@@ -0,0 +1,58 @@
1
+ Metadata-Version: 2.5
2
+ Name: humansand
3
+ Version: 0.1.0
4
+ Summary: The official Python SDK for the Persimmon user model by humans&
5
+ Project-URL: Documentation, https://persimmon.humansand.ai/docs
6
+ Project-URL: Homepage, https://persimmon.humansand.ai
7
+ Author: humans&
8
+ Classifier: Intended Audience :: Developers
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Typing :: Typed
11
+ Requires-Python: >=3.12
12
+ Requires-Dist: httpx<1,>=0.27
13
+ Description-Content-Type: text/markdown
14
+
15
+ # humansand
16
+
17
+ The official Python SDK for Persimmon, a user model by humans&.
18
+ Create a conversation, request a turn, and control the history sent with each request.
19
+
20
+ Requires Python 3.12 or later. The package name is `humansand`; the Python
21
+ import is `user_model`.
22
+
23
+ ## Install
24
+
25
+ ```sh
26
+ pip install humansand
27
+ ```
28
+
29
+ Get an API key from the playground's API page. Store it in your secret manager
30
+ and load it into the `USER_MODEL_API_KEY` environment variable.
31
+
32
+ ## Quickstart
33
+
34
+ ```python
35
+ from user_model import Persimmon
36
+
37
+ with Persimmon() as client:
38
+ conversation = client.conversations.create(
39
+ model="persimmon-v0.1",
40
+ participants=[
41
+ {"name": "Maya", "description": "Product lead. Calm and direct."},
42
+ {"name": "Theo", "description": "Engineer. Careful and practical."},
43
+ ],
44
+ setting="A team discusses a product launch.",
45
+ )
46
+ turn = conversation.get_turn(speaker="Maya")
47
+ print(turn.content)
48
+ conversation.append_turn(turn)
49
+ ```
50
+
51
+ `get_turn()` returns a turn without saving it to the local history. Call
52
+ `append_turn()` to accept it. Each request sends the current conversation history.
53
+
54
+ Use `AsyncPersimmon` with `async with` and `await` in asynchronous applications.
55
+ Both clients close their HTTP connections when their context ends.
56
+
57
+ See the [Python SDK guide](https://persimmon.humansand.ai/docs#sdk/quickstart)
58
+ for asynchronous examples, error handling, pagination, and configuration.
@@ -0,0 +1,44 @@
1
+ # humansand
2
+
3
+ The official Python SDK for Persimmon, a user model by humans&.
4
+ Create a conversation, request a turn, and control the history sent with each request.
5
+
6
+ Requires Python 3.12 or later. The package name is `humansand`; the Python
7
+ import is `user_model`.
8
+
9
+ ## Install
10
+
11
+ ```sh
12
+ pip install humansand
13
+ ```
14
+
15
+ Get an API key from the playground's API page. Store it in your secret manager
16
+ and load it into the `USER_MODEL_API_KEY` environment variable.
17
+
18
+ ## Quickstart
19
+
20
+ ```python
21
+ from user_model import Persimmon
22
+
23
+ with Persimmon() as client:
24
+ conversation = client.conversations.create(
25
+ model="persimmon-v0.1",
26
+ participants=[
27
+ {"name": "Maya", "description": "Product lead. Calm and direct."},
28
+ {"name": "Theo", "description": "Engineer. Careful and practical."},
29
+ ],
30
+ setting="A team discusses a product launch.",
31
+ )
32
+ turn = conversation.get_turn(speaker="Maya")
33
+ print(turn.content)
34
+ conversation.append_turn(turn)
35
+ ```
36
+
37
+ `get_turn()` returns a turn without saving it to the local history. Call
38
+ `append_turn()` to accept it. Each request sends the current conversation history.
39
+
40
+ Use `AsyncPersimmon` with `async with` and `await` in asynchronous applications.
41
+ Both clients close their HTTP connections when their context ends.
42
+
43
+ See the [Python SDK guide](https://persimmon.humansand.ai/docs#sdk/quickstart)
44
+ for asynchronous examples, error handling, pagination, and configuration.
@@ -0,0 +1,63 @@
1
+ """The first-party ``humansand`` SDK: a typed client for the Persimmon API.
2
+
3
+ Install ``humansand`` and use ``from user_model import Persimmon``.
4
+ The SDK uses httpx and has no dependency on the API server. The documented
5
+ surface (developer portal, "Python SDK" tab) is the contract:
6
+
7
+ - ``Persimmon`` / ``AsyncPersimmon``: ``conversations.create/get/list/archive``,
8
+ ``models.list()``.
9
+ - ``conv.turns`` is the local trajectory (the API is stateless).
10
+ ``conv.get_turn(speaker=None)`` sends it and returns one ``Turn`` WITHOUT
11
+ appending; ``conv.append_turn(turn)`` is the explicit local accept — edit
12
+ ``turn.content`` first (fill in a hand-off) or discard the turn instead.
13
+ - Retries are conservative: 429s wait for ``Retry-After`` and connection
14
+ failures retry within a bounded budget; a call that times out mid-flight
15
+ surfaces as an error (the server may already have generated that turn).
16
+
17
+ Layout: ``types``/``errors`` hold the shared data surface, ``_wire`` the
18
+ package-internal request helpers, ``sync_client``/``async_client`` the two
19
+ mirrored clients.
20
+ """
21
+
22
+ from ._wire import VERSION
23
+ from .async_client import AsyncConversation, AsyncConversationPage, AsyncPersimmon
24
+ from .errors import (
25
+ APIConnectionError,
26
+ APITimeoutError,
27
+ AuthenticationError,
28
+ ContentPolicyError,
29
+ ConversationArchivedError,
30
+ InvalidRequestError,
31
+ NotFoundError,
32
+ PersimmonError,
33
+ RateLimitError,
34
+ UpstreamError,
35
+ )
36
+ from .sync_client import Conversation, ConversationPage, Persimmon
37
+ from .types import Model, Participant, Turn, Usage
38
+
39
+ __version__ = VERSION
40
+
41
+ __all__ = [
42
+ "APIConnectionError",
43
+ "APITimeoutError",
44
+ "AsyncConversation",
45
+ "AsyncConversationPage",
46
+ "AsyncPersimmon",
47
+ "AuthenticationError",
48
+ "ContentPolicyError",
49
+ "Conversation",
50
+ "ConversationArchivedError",
51
+ "ConversationPage",
52
+ "InvalidRequestError",
53
+ "Model",
54
+ "NotFoundError",
55
+ "RateLimitError",
56
+ "Participant",
57
+ "Turn",
58
+ "UpstreamError",
59
+ "Usage",
60
+ "Persimmon",
61
+ "PersimmonError",
62
+ "__version__",
63
+ ]
@@ -0,0 +1,144 @@
1
+ """Package-internal wire helpers shared by the sync and async clients."""
2
+
3
+ import os
4
+ from collections.abc import Mapping, Sequence
5
+
6
+ import httpx
7
+
8
+ from .errors import ERROR_TYPES, AuthenticationError, PersimmonError
9
+ from .types import Participant, Turn, Usage
10
+
11
+ VERSION = "0.1.0"
12
+ DEFAULT_BASE_URL = "https://api.persimmon.humansand.ai/v1"
13
+ DEFAULT_TIMEOUT_SECONDS = 300.0
14
+
15
+ # Conservative retry budget (documented): 429s wait for Retry-After, failed
16
+ # connections retry; anything else — including timeouts, which may already
17
+ # have generated and billed a turn — surfaces immediately.
18
+ MAX_RATE_LIMIT_RETRIES = 2
19
+ MAX_CONNECT_RETRIES = 2
20
+ # One retry only: a 502 is documented as "nothing returned or billed", but a
21
+ # retried turn can take minutes, so the budget stays minimal.
22
+ MAX_UPSTREAM_RETRIES = 1
23
+ UPSTREAM_RETRY_DELAY_SECONDS = 1.0
24
+ MAX_RETRY_AFTER_SECONDS = 30.0
25
+
26
+
27
+ def request_headers(api_key: str) -> dict[str, str]:
28
+ return {"Authorization": f"Bearer {api_key}", "User-Agent": f"humansand-python/{VERSION}"}
29
+
30
+
31
+ def resolve_api_key(api_key: str | None) -> str:
32
+ resolved = api_key or os.environ.get("USER_MODEL_API_KEY", "")
33
+ if not resolved:
34
+ raise AuthenticationError("no API key: pass api_key or set USER_MODEL_API_KEY", type="authentication_error", code=401)
35
+ return resolved
36
+
37
+
38
+ def error_from_response(response: httpx.Response) -> PersimmonError:
39
+ request_id = response.headers.get("x-request-id")
40
+ if response.headers.get("content-type", "").startswith("application/json"):
41
+ try:
42
+ envelope = response.json().get("error")
43
+ except ValueError:
44
+ envelope = None
45
+ if isinstance(envelope, dict) and isinstance(envelope.get("message"), str):
46
+ error_type = str(envelope.get("type", "api_error"))
47
+ error_class = ERROR_TYPES.get(error_type, PersimmonError)
48
+ return error_class(envelope["message"], type=error_type, code=response.status_code, request_id=request_id)
49
+ return PersimmonError(f"the API returned HTTP {response.status_code}", type="api_error", code=response.status_code, request_id=request_id)
50
+
51
+
52
+ def is_enveloped_error(response: httpx.Response) -> bool:
53
+ """True when the body is the API's own Error envelope. An LB/proxy 502
54
+ without it may follow a turn that was already generated and billed, so it
55
+ must surface instead of being retried."""
56
+ if not response.headers.get("content-type", "").startswith("application/json"):
57
+ return False
58
+ try:
59
+ envelope = response.json().get("error")
60
+ except ValueError:
61
+ return False
62
+ return isinstance(envelope, dict) and isinstance(envelope.get("message"), str)
63
+
64
+
65
+ def retry_after_seconds(response: httpx.Response) -> float | None:
66
+ """The server's requested wait, or None when it exceeds the retry budget."""
67
+ try:
68
+ seconds = float(response.headers.get("Retry-After", ""))
69
+ except ValueError:
70
+ return None
71
+ return seconds if 0 <= seconds <= MAX_RETRY_AFTER_SECONDS else None
72
+
73
+
74
+ def turn_from(body: dict) -> Turn:
75
+ return Turn(
76
+ id=body["id"],
77
+ name=body["name"],
78
+ content=body["content"],
79
+ timestamp=body.get("timestamp"),
80
+ finish_reason=body["finish_reason"],
81
+ usage=Usage(
82
+ prompt_tokens=body["usage"]["prompt_tokens"],
83
+ completion_tokens=body["usage"]["completion_tokens"],
84
+ total_tokens=body["usage"]["total_tokens"],
85
+ # .get: tolerate servers predating the cached-token detail.
86
+ cached_prompt_tokens=(body["usage"].get("prompt_tokens_details") or {}).get("cached_tokens", 0),
87
+ ),
88
+ )
89
+
90
+
91
+ def history_entry(turn: "Turn | dict[str, str]") -> dict[str, str]:
92
+ """The wire-shaped history entry for a turn joining the trajectory."""
93
+ if isinstance(turn, Turn):
94
+ name, content, timestamp = turn.name, turn.content, turn.timestamp
95
+ else:
96
+ name = turn["name"]
97
+ content = turn.get("content")
98
+ timestamp_value = turn.get("timestamp")
99
+ if timestamp_value is not None and not isinstance(timestamp_value, str):
100
+ # A datetime here would be silently dropped and surface later as a
101
+ # confusing server-side 400 in real-timestamp conversations.
102
+ raise ValueError("turn timestamps must be ISO-8601 strings (call .isoformat() on datetimes)")
103
+ timestamp = timestamp_value
104
+ if not isinstance(content, str):
105
+ raise ValueError(f"a turn needs string content before it joins the trajectory (got {content!r} for {name!r}); fill in hand-offs or drop them")
106
+ entry = {"name": name, "content": content}
107
+ if timestamp is not None:
108
+ entry["timestamp"] = timestamp
109
+ return entry
110
+
111
+
112
+ def participants_payload(participants: Sequence[Participant | Mapping[str, str | bool]]) -> list[dict[str, str | bool]]:
113
+ payload: list[dict[str, str | bool]] = []
114
+ for participant in participants:
115
+ if isinstance(participant, Participant):
116
+ entry: dict[str, str | bool] = {"name": participant.name}
117
+ if participant.description:
118
+ entry["description"] = participant.description
119
+ if not participant.generate_content:
120
+ entry["generate_content"] = False
121
+ payload.append(entry)
122
+ else:
123
+ payload.append(dict(participant))
124
+ return payload
125
+
126
+
127
+ def conversation_fields(body: dict) -> dict:
128
+ return {
129
+ "id": body["id"],
130
+ "model": body["model"],
131
+ "setting": body.get("setting"),
132
+ "timestamps": body.get("timestamps", False),
133
+ "participants": tuple(
134
+ Participant(
135
+ name=entry["name"],
136
+ description=entry.get("description", ""),
137
+ generate_content=entry.get("generate_content", True),
138
+ )
139
+ for entry in body["participants"]
140
+ ),
141
+ "metadata": dict(body.get("metadata", {})),
142
+ "status": body["status"],
143
+ "created": body["created"],
144
+ }
@@ -0,0 +1,238 @@
1
+ """The async client (``AsyncPersimmon``); mirrors ``sync_client`` exactly.
2
+
3
+ Kept in lockstep with the sync module by
4
+ ``test_async_client_mirrors_the_sync_surface``.
5
+ """
6
+
7
+ import asyncio
8
+ import dataclasses
9
+ import uuid
10
+ from collections.abc import Mapping, Sequence
11
+
12
+ import httpx
13
+
14
+ from ._wire import (
15
+ DEFAULT_BASE_URL,
16
+ DEFAULT_TIMEOUT_SECONDS,
17
+ MAX_CONNECT_RETRIES,
18
+ MAX_RATE_LIMIT_RETRIES,
19
+ MAX_UPSTREAM_RETRIES,
20
+ UPSTREAM_RETRY_DELAY_SECONDS,
21
+ conversation_fields,
22
+ error_from_response,
23
+ history_entry,
24
+ is_enveloped_error,
25
+ participants_payload,
26
+ request_headers,
27
+ resolve_api_key,
28
+ retry_after_seconds,
29
+ turn_from,
30
+ )
31
+ from .errors import APIConnectionError, APITimeoutError, PersimmonError
32
+ from .types import Model, Participant, Turn
33
+
34
+
35
+ @dataclasses.dataclass(frozen=True)
36
+ class AsyncConversationPage:
37
+ """One page of conversations; ``has_more`` drives the pagination loop."""
38
+
39
+ items: list["AsyncConversation"]
40
+ has_more: bool
41
+
42
+
43
+ class AsyncPersimmon:
44
+ """Async client. Pass ``http_client`` to share one connection pool (and,
45
+ in tests or in-process consumers, an ``httpx.ASGITransport``)."""
46
+
47
+ def __init__(
48
+ self,
49
+ api_key: str | None = None,
50
+ *,
51
+ base_url: str = DEFAULT_BASE_URL,
52
+ timeout: float = DEFAULT_TIMEOUT_SECONDS,
53
+ http_client: httpx.AsyncClient | None = None,
54
+ ) -> None:
55
+ self._api_key = resolve_api_key(api_key)
56
+ self._base_url = base_url.rstrip("/")
57
+ self._owns_http = http_client is None
58
+ self._http = http_client if http_client is not None else httpx.AsyncClient(timeout=timeout)
59
+ self.conversations = _AsyncConversations(self)
60
+ self.models = _AsyncModels(self)
61
+
62
+ async def request(
63
+ self,
64
+ method: str,
65
+ path: str,
66
+ json: dict | None = None,
67
+ *,
68
+ headers: Mapping[str, str] | None = None,
69
+ idempotency_key: str | None = None,
70
+ ) -> dict:
71
+ extra_headers = dict(headers or {})
72
+ if any(name.lower() == "authorization" for name in extra_headers):
73
+ raise ValueError("request headers cannot override Authorization")
74
+ outbound_headers = request_headers(self._api_key)
75
+ outbound_headers.update(extra_headers)
76
+ existing_key = next((value for name, value in outbound_headers.items() if name.lower() == "idempotency-key"), None)
77
+ if idempotency_key is not None and existing_key is not None and idempotency_key != existing_key:
78
+ raise ValueError("conflicting Idempotency-Key values")
79
+ idempotency_key = idempotency_key or existing_key
80
+ if method.upper() == "POST" and path.partition("?")[0].endswith("/turns"):
81
+ idempotency_key = idempotency_key or uuid.uuid4().hex
82
+ if idempotency_key is not None and existing_key is None:
83
+ outbound_headers["Idempotency-Key"] = idempotency_key
84
+ rate_limit_retries = 0
85
+ connect_retries = 0
86
+ upstream_retries = 0
87
+ while True:
88
+ try:
89
+ response = await self._http.request(method, f"{self._base_url}{path}", json=json, headers=outbound_headers)
90
+ except (httpx.ConnectError, httpx.ConnectTimeout):
91
+ if connect_retries >= MAX_CONNECT_RETRIES:
92
+ raise APIConnectionError("could not connect to the API", type="connection_error", code=0, idempotency_key=idempotency_key) from None
93
+ connect_retries += 1
94
+ await asyncio.sleep(0.5 * connect_retries)
95
+ continue
96
+ except httpx.TimeoutException as error:
97
+ # Deliberately NOT retried: the server may already have
98
+ # generated (and billed) the turn this call asked for.
99
+ raise APITimeoutError(
100
+ "the API call timed out; the server may already have generated (and billed) the requested turn",
101
+ type="timeout_error",
102
+ code=0,
103
+ idempotency_key=idempotency_key,
104
+ ) from error
105
+ except httpx.HTTPError as error:
106
+ raise APIConnectionError(f"transport failure talking to the API: {error}", type="connection_error", code=0, idempotency_key=idempotency_key) from error
107
+ if response.status_code == 502 and upstream_retries < MAX_UPSTREAM_RETRIES and is_enveloped_error(response):
108
+ # The app's own 502 is documented as returned-and-billed-nothing;
109
+ # a bare LB/proxy 502 gets no such guarantee and must surface.
110
+ upstream_retries += 1
111
+ await asyncio.sleep(UPSTREAM_RETRY_DELAY_SECONDS)
112
+ continue
113
+ if response.status_code == 429 and rate_limit_retries < MAX_RATE_LIMIT_RETRIES:
114
+ wait_seconds = retry_after_seconds(response)
115
+ if wait_seconds is not None:
116
+ rate_limit_retries += 1
117
+ await asyncio.sleep(wait_seconds)
118
+ continue
119
+ if response.status_code >= 400:
120
+ error = error_from_response(response)
121
+ error.idempotency_key = idempotency_key
122
+ raise error
123
+ try:
124
+ return response.json()
125
+ except ValueError as error:
126
+ # A proxy or middlebox answering 2xx with non-JSON must not
127
+ # surface as a raw decode error.
128
+ raise PersimmonError("the API returned a non-JSON success response", type="api_error", code=response.status_code, idempotency_key=idempotency_key) from error
129
+
130
+ async def aclose(self) -> None:
131
+ if self._owns_http:
132
+ await self._http.aclose()
133
+
134
+ async def __aenter__(self) -> "AsyncPersimmon":
135
+ return self
136
+
137
+ async def __aexit__(self, *exc_info: object) -> None:
138
+ await self.aclose()
139
+
140
+
141
+ class _AsyncConversations:
142
+ def __init__(self, client: AsyncPersimmon) -> None:
143
+ self._client = client
144
+
145
+ async def create(
146
+ self,
147
+ *,
148
+ model: str,
149
+ participants: Sequence[Participant | Mapping[str, str | bool]],
150
+ setting: str | None = None,
151
+ timestamps: bool = False,
152
+ metadata: dict[str, str] | None = None,
153
+ ) -> "AsyncConversation":
154
+ payload: dict = {"model": model, "participants": participants_payload(participants)}
155
+ if setting is not None:
156
+ payload["setting"] = setting
157
+ if timestamps:
158
+ payload["timestamps"] = True
159
+ if metadata:
160
+ payload["metadata"] = metadata
161
+ body = await self._client.request("POST", "/conversations", json=payload)
162
+ return AsyncConversation(self._client, **conversation_fields(body))
163
+
164
+ async def get(self, conversation_id: str) -> "AsyncConversation":
165
+ body = await self._client.request("GET", f"/conversations/{conversation_id}")
166
+ return AsyncConversation(self._client, **conversation_fields(body))
167
+
168
+ async def list(self, *, limit: int = 20, after: str | None = None) -> AsyncConversationPage:
169
+ query = f"?limit={limit}" + (f"&after={after}" if after else "")
170
+ body = await self._client.request("GET", f"/conversations{query}")
171
+ items = [AsyncConversation(self._client, **conversation_fields(entry)) for entry in body["data"]]
172
+ return AsyncConversationPage(items=items, has_more=body["has_more"])
173
+
174
+ async def archive(self, conversation_id: str) -> None:
175
+ await self._client.request("DELETE", f"/conversations/{conversation_id}")
176
+
177
+
178
+ class _AsyncModels:
179
+ def __init__(self, client: AsyncPersimmon) -> None:
180
+ self._client = client
181
+
182
+ async def list(self) -> list[Model]:
183
+ body = await self._client.request("GET", "/models")
184
+ return [Model(id=entry["id"], created=entry["created"], owned_by=entry["owned_by"]) for entry in body["data"]]
185
+
186
+
187
+ class AsyncConversation:
188
+ """A conversation handle plus the local trajectory (``turns``). The API is
189
+ stateless: the server stores the frozen setup only, and every ``get_turn``
190
+ sends the full local history."""
191
+
192
+ def __init__(
193
+ self,
194
+ client: AsyncPersimmon,
195
+ *,
196
+ id: str, # noqa: A002 - mirrors the wire field
197
+ model: str,
198
+ setting: str | None,
199
+ timestamps: bool,
200
+ participants: tuple[Participant, ...],
201
+ metadata: dict[str, str],
202
+ status: str,
203
+ created: int,
204
+ ) -> None:
205
+ self._client = client
206
+ self.id = id
207
+ self.model = model
208
+ self.setting = setting
209
+ self.timestamps = timestamps
210
+ self.participants = participants
211
+ self.metadata = metadata
212
+ self.status = status
213
+ self.created = created
214
+ self.turns: list[dict[str, str]] = []
215
+
216
+ async def get_turn(self, speaker: str | None = None, *, max_tokens: int | None = None, user: str | None = None, idempotency_key: str | None = None) -> Turn:
217
+ """One generated turn (or a hand-off) for the current trajectory.
218
+
219
+ The returned turn is NOT appended — accept it with ``append_turn``,
220
+ edit it first, or discard it and call again. ``user`` is an opaque
221
+ end-user tag for the caller's own attribution in usage records. Preserve
222
+ ``idempotency_key`` and the identical history to recover a timed-out
223
+ turn; errors expose the automatically generated key when omitted."""
224
+ payload: dict = {"turns": list(self.turns)}
225
+ if speaker is not None:
226
+ payload["speaker"] = speaker
227
+ if max_tokens is not None:
228
+ payload["max_tokens"] = max_tokens
229
+ if user is not None:
230
+ payload["user"] = user
231
+ body = await self._client.request("POST", f"/conversations/{self.id}/turns", json=payload, idempotency_key=idempotency_key)
232
+ return turn_from(body)
233
+
234
+ def append_turn(self, turn: "Turn | dict[str, str]") -> None:
235
+ """Append a turn to the local trajectory (no network call). Takes a
236
+ ``Turn`` from ``get_turn`` or a plain dict for turns you write; the
237
+ content must be a string, so fill in hand-offs first."""
238
+ self.turns.append(history_entry(turn))
@@ -0,0 +1,68 @@
1
+ """The SDK error taxonomy.
2
+
3
+ Every failure raises ``PersimmonError``; the server's error taxonomy maps to a
4
+ subclass per ``type`` so callers can catch precisely (``except
5
+ RateLimitError``) or broadly (``except PersimmonError``). ``type`` and ``code``
6
+ stay populated either way, and errors carry the server's ``request_id`` when
7
+ one was received — quote it when reporting an issue.
8
+ """
9
+
10
+
11
+ class PersimmonError(Exception):
12
+ """An API failure, carrying the error taxonomy's ``type`` and HTTP ``code``."""
13
+
14
+ def __init__(self, message: str, *, type: str, code: int, request_id: str | None = None, idempotency_key: str | None = None) -> None: # noqa: A002 - `type` is the documented field name
15
+ super().__init__(message)
16
+ self.type = type
17
+ self.code = code
18
+ self.request_id = request_id
19
+ self.idempotency_key = idempotency_key
20
+
21
+
22
+ class AuthenticationError(PersimmonError):
23
+ """401 ``authentication_error``: missing, unknown, or revoked key."""
24
+
25
+
26
+ class InvalidRequestError(PersimmonError):
27
+ """400 ``invalid_request_error``: validation failure."""
28
+
29
+
30
+ class ContentPolicyError(PersimmonError):
31
+ """400 ``content_policy_error``: reserved for the moderation phase."""
32
+
33
+
34
+ class NotFoundError(PersimmonError):
35
+ """404 ``not_found_error``: conversation or model unknown (or not yours)."""
36
+
37
+
38
+ class ConversationArchivedError(PersimmonError):
39
+ """410 ``conversation_archived``: the conversation was archived."""
40
+
41
+
42
+ class RateLimitError(PersimmonError):
43
+ """429 ``rate_limit_error``, raised once the SDK's retry budget is spent."""
44
+
45
+
46
+ class UpstreamError(PersimmonError):
47
+ """502 ``upstream_error``: the model backend failed; nothing was billed."""
48
+
49
+
50
+ class APITimeoutError(PersimmonError):
51
+ """A call timed out mid-flight; the server may already have generated
52
+ (and billed) the requested turn, so the SDK never blind-retries it."""
53
+
54
+
55
+ class APIConnectionError(PersimmonError):
56
+ """The connection to the API failed (after the bounded retry budget)."""
57
+
58
+
59
+ # The server's error taxonomy -> subclass; unknown types raise the base class.
60
+ ERROR_TYPES: dict[str, type[PersimmonError]] = {
61
+ "authentication_error": AuthenticationError,
62
+ "invalid_request_error": InvalidRequestError,
63
+ "content_policy_error": ContentPolicyError,
64
+ "not_found_error": NotFoundError,
65
+ "conversation_archived": ConversationArchivedError,
66
+ "rate_limit_error": RateLimitError,
67
+ "upstream_error": UpstreamError,
68
+ }
File without changes
@@ -0,0 +1,44 @@
1
+ [project]
2
+ name = "humansand"
3
+ dynamic = ["version"]
4
+ description = "The official Python SDK for the Persimmon user model by humans&"
5
+ readme = "README.md"
6
+ requires-python = ">=3.12"
7
+ authors = [{ name = "humans&" }]
8
+ dependencies = ["httpx>=0.27,<1"]
9
+ classifiers = [
10
+ "Intended Audience :: Developers",
11
+ "Programming Language :: Python :: 3",
12
+ "Typing :: Typed",
13
+ ]
14
+
15
+ [project.urls]
16
+ Documentation = "https://persimmon.humansand.ai/docs"
17
+ Homepage = "https://persimmon.humansand.ai"
18
+
19
+ [build-system]
20
+ requires = ["hatchling>=1.27,<2"]
21
+ build-backend = "hatchling.build"
22
+
23
+ [tool.hatch.version]
24
+ path = "_wire.py"
25
+ pattern = 'VERSION = "(?P<version>[^\"]+)"'
26
+
27
+ # The same client files serve usersim.sdk in the service and user_model in the
28
+ # standalone SDK. Explicit selection keeps server code out of the release.
29
+ [tool.hatch.build.targets.wheel]
30
+ only-include = [
31
+ "__init__.py",
32
+ "_wire.py",
33
+ "async_client.py",
34
+ "errors.py",
35
+ "sync_client.py",
36
+ "types.py",
37
+ "py.typed",
38
+ ]
39
+
40
+ [tool.hatch.build.targets.wheel.sources]
41
+ "" = "user_model"
42
+
43
+ [tool.hatch.build.targets.sdist]
44
+ include = ["/*.py", "/py.typed", "/pyproject.toml", "/README.md"]
@@ -0,0 +1,237 @@
1
+ """The synchronous client (``Persimmon``); the documented external surface.
2
+
3
+ Kept in lockstep with the async module by
4
+ ``test_async_client_mirrors_the_sync_surface``.
5
+ """
6
+
7
+ import dataclasses
8
+ import time
9
+ import uuid
10
+ from collections.abc import Mapping, Sequence
11
+
12
+ import httpx
13
+
14
+ from ._wire import (
15
+ DEFAULT_BASE_URL,
16
+ DEFAULT_TIMEOUT_SECONDS,
17
+ MAX_CONNECT_RETRIES,
18
+ MAX_RATE_LIMIT_RETRIES,
19
+ MAX_UPSTREAM_RETRIES,
20
+ UPSTREAM_RETRY_DELAY_SECONDS,
21
+ conversation_fields,
22
+ error_from_response,
23
+ history_entry,
24
+ is_enveloped_error,
25
+ participants_payload,
26
+ request_headers,
27
+ resolve_api_key,
28
+ retry_after_seconds,
29
+ turn_from,
30
+ )
31
+ from .errors import APIConnectionError, APITimeoutError, PersimmonError
32
+ from .types import Model, Participant, Turn
33
+
34
+
35
+ @dataclasses.dataclass(frozen=True)
36
+ class ConversationPage:
37
+ """One page of conversations; ``has_more`` drives the pagination loop."""
38
+
39
+ items: list["Conversation"]
40
+ has_more: bool
41
+
42
+
43
+ class Persimmon:
44
+ """Sync client; the documented external surface."""
45
+
46
+ def __init__(
47
+ self,
48
+ api_key: str | None = None,
49
+ *,
50
+ base_url: str = DEFAULT_BASE_URL,
51
+ timeout: float = DEFAULT_TIMEOUT_SECONDS,
52
+ http_client: httpx.Client | None = None,
53
+ ) -> None:
54
+ self._api_key = resolve_api_key(api_key)
55
+ self._base_url = base_url.rstrip("/")
56
+ self._owns_http = http_client is None
57
+ self._http = http_client if http_client is not None else httpx.Client(timeout=timeout)
58
+ self.conversations = _Conversations(self)
59
+ self.models = _Models(self)
60
+
61
+ def request(
62
+ self,
63
+ method: str,
64
+ path: str,
65
+ json: dict | None = None,
66
+ *,
67
+ headers: Mapping[str, str] | None = None,
68
+ idempotency_key: str | None = None,
69
+ ) -> dict:
70
+ extra_headers = dict(headers or {})
71
+ if any(name.lower() == "authorization" for name in extra_headers):
72
+ raise ValueError("request headers cannot override Authorization")
73
+ outbound_headers = request_headers(self._api_key)
74
+ outbound_headers.update(extra_headers)
75
+ existing_key = next((value for name, value in outbound_headers.items() if name.lower() == "idempotency-key"), None)
76
+ if idempotency_key is not None and existing_key is not None and idempotency_key != existing_key:
77
+ raise ValueError("conflicting Idempotency-Key values")
78
+ idempotency_key = idempotency_key or existing_key
79
+ if method.upper() == "POST" and path.partition("?")[0].endswith("/turns"):
80
+ idempotency_key = idempotency_key or uuid.uuid4().hex
81
+ if idempotency_key is not None and existing_key is None:
82
+ outbound_headers["Idempotency-Key"] = idempotency_key
83
+ rate_limit_retries = 0
84
+ connect_retries = 0
85
+ upstream_retries = 0
86
+ while True:
87
+ try:
88
+ response = self._http.request(method, f"{self._base_url}{path}", json=json, headers=outbound_headers)
89
+ except (httpx.ConnectError, httpx.ConnectTimeout):
90
+ if connect_retries >= MAX_CONNECT_RETRIES:
91
+ raise APIConnectionError("could not connect to the API", type="connection_error", code=0, idempotency_key=idempotency_key) from None
92
+ connect_retries += 1
93
+ time.sleep(0.5 * connect_retries)
94
+ continue
95
+ except httpx.TimeoutException as error:
96
+ # Deliberately NOT retried: the server may already have
97
+ # generated (and billed) the turn this call asked for.
98
+ raise APITimeoutError(
99
+ "the API call timed out; the server may already have generated (and billed) the requested turn",
100
+ type="timeout_error",
101
+ code=0,
102
+ idempotency_key=idempotency_key,
103
+ ) from error
104
+ except httpx.HTTPError as error:
105
+ raise APIConnectionError(f"transport failure talking to the API: {error}", type="connection_error", code=0, idempotency_key=idempotency_key) from error
106
+ if response.status_code == 502 and upstream_retries < MAX_UPSTREAM_RETRIES and is_enveloped_error(response):
107
+ # The app's own 502 is documented as returned-and-billed-nothing;
108
+ # a bare LB/proxy 502 gets no such guarantee and must surface.
109
+ upstream_retries += 1
110
+ time.sleep(UPSTREAM_RETRY_DELAY_SECONDS)
111
+ continue
112
+ if response.status_code == 429 and rate_limit_retries < MAX_RATE_LIMIT_RETRIES:
113
+ wait_seconds = retry_after_seconds(response)
114
+ if wait_seconds is not None:
115
+ rate_limit_retries += 1
116
+ time.sleep(wait_seconds)
117
+ continue
118
+ if response.status_code >= 400:
119
+ error = error_from_response(response)
120
+ error.idempotency_key = idempotency_key
121
+ raise error
122
+ try:
123
+ return response.json()
124
+ except ValueError as error:
125
+ # A proxy or middlebox answering 2xx with non-JSON must not
126
+ # surface as a raw decode error.
127
+ raise PersimmonError("the API returned a non-JSON success response", type="api_error", code=response.status_code, idempotency_key=idempotency_key) from error
128
+
129
+ def close(self) -> None:
130
+ if self._owns_http:
131
+ self._http.close()
132
+
133
+ def __enter__(self) -> "Persimmon":
134
+ return self
135
+
136
+ def __exit__(self, *exc_info: object) -> None:
137
+ self.close()
138
+
139
+
140
+ class _Conversations:
141
+ def __init__(self, client: Persimmon) -> None:
142
+ self._client = client
143
+
144
+ def create(
145
+ self,
146
+ *,
147
+ model: str,
148
+ participants: Sequence[Participant | Mapping[str, str | bool]],
149
+ setting: str | None = None,
150
+ timestamps: bool = False,
151
+ metadata: dict[str, str] | None = None,
152
+ ) -> "Conversation":
153
+ payload: dict = {"model": model, "participants": participants_payload(participants)}
154
+ if setting is not None:
155
+ payload["setting"] = setting
156
+ if timestamps:
157
+ payload["timestamps"] = True
158
+ if metadata:
159
+ payload["metadata"] = metadata
160
+ body = self._client.request("POST", "/conversations", json=payload)
161
+ return Conversation(self._client, **conversation_fields(body))
162
+
163
+ def get(self, conversation_id: str) -> "Conversation":
164
+ body = self._client.request("GET", f"/conversations/{conversation_id}")
165
+ return Conversation(self._client, **conversation_fields(body))
166
+
167
+ def list(self, *, limit: int = 20, after: str | None = None) -> ConversationPage:
168
+ query = f"?limit={limit}" + (f"&after={after}" if after else "")
169
+ body = self._client.request("GET", f"/conversations{query}")
170
+ items = [Conversation(self._client, **conversation_fields(entry)) for entry in body["data"]]
171
+ return ConversationPage(items=items, has_more=body["has_more"])
172
+
173
+ def archive(self, conversation_id: str) -> None:
174
+ self._client.request("DELETE", f"/conversations/{conversation_id}")
175
+
176
+
177
+ class _Models:
178
+ def __init__(self, client: Persimmon) -> None:
179
+ self._client = client
180
+
181
+ def list(self) -> list[Model]:
182
+ body = self._client.request("GET", "/models")
183
+ return [Model(id=entry["id"], created=entry["created"], owned_by=entry["owned_by"]) for entry in body["data"]]
184
+
185
+
186
+ class Conversation:
187
+ """A conversation handle plus the local trajectory (``turns``). The API is
188
+ stateless: the server stores the frozen setup only, and every ``get_turn``
189
+ sends the full local history."""
190
+
191
+ def __init__(
192
+ self,
193
+ client: Persimmon,
194
+ *,
195
+ id: str, # noqa: A002 - mirrors the wire field
196
+ model: str,
197
+ setting: str | None,
198
+ timestamps: bool,
199
+ participants: tuple[Participant, ...],
200
+ metadata: dict[str, str],
201
+ status: str,
202
+ created: int,
203
+ ) -> None:
204
+ self._client = client
205
+ self.id = id
206
+ self.model = model
207
+ self.setting = setting
208
+ self.timestamps = timestamps
209
+ self.participants = participants
210
+ self.metadata = metadata
211
+ self.status = status
212
+ self.created = created
213
+ self.turns: list[dict[str, str]] = []
214
+
215
+ def get_turn(self, speaker: str | None = None, *, max_tokens: int | None = None, user: str | None = None, idempotency_key: str | None = None) -> Turn:
216
+ """One generated turn (or a hand-off) for the current trajectory.
217
+
218
+ The returned turn is NOT appended — accept it with ``append_turn``,
219
+ edit it first, or discard it and call again. ``user`` is an opaque
220
+ end-user tag for the caller's own attribution in usage records. Preserve
221
+ ``idempotency_key`` and the identical history to recover a timed-out
222
+ turn; errors expose the automatically generated key when omitted."""
223
+ payload: dict = {"turns": list(self.turns)}
224
+ if speaker is not None:
225
+ payload["speaker"] = speaker
226
+ if max_tokens is not None:
227
+ payload["max_tokens"] = max_tokens
228
+ if user is not None:
229
+ payload["user"] = user
230
+ body = self._client.request("POST", f"/conversations/{self.id}/turns", json=payload, idempotency_key=idempotency_key)
231
+ return turn_from(body)
232
+
233
+ def append_turn(self, turn: "Turn | dict[str, str]") -> None:
234
+ """Append a turn to the local trajectory (no network call). Takes a
235
+ ``Turn`` from ``get_turn`` or a plain dict for turns you write; the
236
+ content must be a string, so fill in hand-offs first."""
237
+ self.turns.append(history_entry(turn))
@@ -0,0 +1,43 @@
1
+ """Wire-facing data types shared by the sync and async clients."""
2
+
3
+ import dataclasses
4
+
5
+
6
+ @dataclasses.dataclass(frozen=True)
7
+ class Usage:
8
+ prompt_tokens: int
9
+ completion_tokens: int
10
+ total_tokens: int
11
+ # Wire: usage.prompt_tokens_details.cached_tokens — the cached subset of
12
+ # prompt_tokens (which stays the total), billed at the cached rate.
13
+ cached_prompt_tokens: int = 0
14
+
15
+
16
+ @dataclasses.dataclass
17
+ class Turn:
18
+ """One turn from the API. Deliberately mutable: edit ``content`` before
19
+ ``append_turn`` (fill in a hand-off, tweak a generation) or discard it."""
20
+
21
+ id: str
22
+ name: str
23
+ # None: a hand-off — the speaker's generate_content is False and you
24
+ # write this participant's words.
25
+ content: str | None
26
+ timestamp: str | None
27
+ # None on a hand-off (nothing was generated).
28
+ finish_reason: str | None
29
+ usage: Usage
30
+
31
+
32
+ @dataclasses.dataclass(frozen=True)
33
+ class Participant:
34
+ name: str
35
+ description: str = ""
36
+ generate_content: bool = True
37
+
38
+
39
+ @dataclasses.dataclass(frozen=True)
40
+ class Model:
41
+ id: str
42
+ created: int
43
+ owned_by: str