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.
- humansand-0.1.0/.gitignore +3 -0
- humansand-0.1.0/PKG-INFO +58 -0
- humansand-0.1.0/README.md +44 -0
- humansand-0.1.0/__init__.py +63 -0
- humansand-0.1.0/_wire.py +144 -0
- humansand-0.1.0/async_client.py +238 -0
- humansand-0.1.0/errors.py +68 -0
- humansand-0.1.0/py.typed +0 -0
- humansand-0.1.0/pyproject.toml +44 -0
- humansand-0.1.0/sync_client.py +237 -0
- humansand-0.1.0/types.py +43 -0
humansand-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
]
|
humansand-0.1.0/_wire.py
ADDED
|
@@ -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
|
+
}
|
humansand-0.1.0/py.typed
ADDED
|
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))
|
humansand-0.1.0/types.py
ADDED
|
@@ -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
|