Rhyme Python SDK
Python client for the Rhyme Agent API. An agent reports what it did, one activity per ticket turn, and Rhyme shows it on the agent's Live Activity page.
pip install rhyme-sdk
Requires Python 3.12+.
Quickstart
from rhyme import Activity, ActivityRequest, Rhyme
client = Rhyme(api_key="rhyme_ak1_...", base_url="https://<rhyme-host>/api/agent/v1")
client.me() # smoke-test the key: agent, scopes, limits, today's usage
result = client.post_activity(
Activity(
external_id="zendesk:4822:1",
status="done",
action="draft_reply",
request=ActivityRequest(source="zendesk", id="4822"),
summary="Drafted a reply about a delayed refund",
duration_ms=8400,
)
)
if not result.ok:
print(result.error)
api_key and base_url fall back to the RHYME_API_KEY and RHYME_BASE_URL environment variables. There is no default base URL: you choose which Rhyme region your activity data goes to.
Async
AsyncRhyme has the same methods, as coroutines:
from rhyme import AsyncRhyme
async with AsyncRhyme() as client:
result = await client.post_activity(activity)
HTTP client
Both clients use HTTPX2. To configure proxies, TLS or connection limits, pass your own httpx2.Client (or httpx2.AsyncClient for AsyncRhyme) as http_client=. The SDK doesn't close a client you pass in. Redirects aren't followed: a 3xx raises APIStatusError.
Activities
POST /activities upserts by external_id, so posting the same id again updates the activity (for example pending → done).
- A field you don't set keeps its stored value.
- Setting a field to
Noneclears it. That works for the text fields (requester,ask,summary,outcome,escalation_reason,output),duration_ms,usage,toolsand a reference'surl. Every other field can't be null:Activity(action=None)raisesValueError, so leave the field unset instead. request,occurred_at,workflow,stepandintentare set once. A later, different value is ignored with animmutable_field_ignoredwarning.metadatais merged into the stored metadata.doneandhanded_overare final. A laterpendingorfailedcomes back with resultstale, and nothing is written.- A batch is 1–100 activities. Each item gets its own result, so a
200can still contain rejected items:
batch = client.post_activities(activities)
for item in batch.rejected:
print(item.index, item.error.code, item.error.field)
You can also pass plain dicts in API field names ({"externalId": ..., "status": ...}). They are sent as given, without validation.
Batching
post_activities takes up to 100 activities per call. To send more, use post_all. It posts them in order, in batches of up to 100:
result = client.post_all(activities) # or: await client.post_all(...) with AsyncRhyme
for batch in result.batch_results:
for item in batch.rejected:
print(item.external_id, item.error.code)
for d in result.dropped:
print("dropped", d.activity, d.error)
- If the API refuses a batch as too large (413) or invalid (400),
post_allsplits it and posts the halves. An activity it still refuses on its own is skipped and returned inresult.droppedwith its error, so one bad item can't block the rest. A plain dict that can't be serialised to JSON is handled the same way. - On any other error (network, 5xx, rate limits, auth), it stops and raises
rhyme.PostAllError. The underlying error is its__cause__..batch_resultsand.droppeddescribe what happened before it stopped, and.unsentholds every activity not yet posted, in order, so you can retry exactly those. Activities upsert byexternalId, so resending one is safe.
from rhyme import PostAllError
try:
client.post_all(activities)
except PostAllError as e:
save_for_later(e.unsent)
A key can have a lower per-request limit than 100 (see GET /me). Pass it as max_items:
client.post_all(activities, max_items=client.me().limits.max_items)
post_all keeps nothing between calls. To collect activities as they happen and send them in batches, keep your own list (or queue) and pass it to post_all when it's full or on a timer.
Errors and retries
API, network and configuration errors raise a subclass of rhyme.RhymeError. Invalid arguments, such as a malformed Activity or an empty batch, raise ValueError (pydantic's ValidationError is one).
| Exception | When |
|---|---|
BadRequestError (400) |
Invalid body, e.g. not 1 to 100 activities; see .details |
AuthenticationError (401) |
Missing, unknown or revoked key |
PermissionDeniedError (403) |
The key lacks the scope |
PayloadTooLargeError (413) |
Body over 1 MB |
RateLimitError (429) |
.code is rate_limited or quota_exceeded; .retry_after in seconds |
InternalServerError (5xx) |
Server error |
APIConnectionError / APITimeoutError |
No response |
Every APIStatusError carries .status_code, .code and .request_id. Quote the request id when reporting a problem.
The client retries connection errors, timeouts, 5xx responses and rate_limited up to max_retries times (default 2). It honours Retry-After up to 60 seconds and backs off with jitter otherwise. It never retries quota_exceeded or other 4xx errors. Retrying is safe because activities upsert by external_id.
client = Rhyme(max_retries=5, timeout=30)
Each retry is logged at INFO on the rhyme logger, with the error and its request id.
Testing
rhyme.testing.FakeRhyme has the same methods as Rhyme, but sends nothing. It builds each request body exactly as Rhyme would and records it, then returns every item as created. It doesn't model the API: nothing is stored, merged or rejected.
from rhyme.testing import FakeRhyme
fake = FakeRhyme()
my_agent.run(rhyme=fake)
assert fake.posted[-1]["status"] == "done" # activities in API (camelCase) field names
assert len(fake.batches) == 1 # one entry per post call
Set fake.error to an exception to make the next call raise it, or fake.result to an ActivityBatchResult to make the next post return it (to test how your code handles rejected items, say). fake.me_calls counts me() calls. rhyme.testing.AsyncFakeRhyme does the same for AsyncRhyme.
Type your own code against the RhymeClient protocol (or AsyncRhymeClient), so it accepts either the real client or the fake:
from rhyme import AsyncRhymeClient, RhymeClient
def report_turn(rhyme: RhymeClient, ticket_id: str) -> None: ...
async def report_turn_async(rhyme: AsyncRhymeClient, ticket_id: str) -> None: ...
Development
uv sync
uv run pytest
uv run ruff check && uv run ruff format --check
uv run pyright
pre-commit install --hook-type pre-commit --hook-type pre-push
Releasing
- Bump
versioninpyproject.tomland add aCHANGELOG.mdentry. - Publish a GitHub release tagged
vX.Y.Z. The release workflow tests the code, builds it and uploads it to PyPI using trusted publishing.
License
Apache-2.0. See LICENSE.
Metadata
Release files for rhyme-sdk 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rhyme_sdk-0.1.1.tar.gz | 18.5 kB | Without provenance | Details for rhyme_sdk-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rhyme_sdk-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for rhyme_sdk-0.1.1-py3-none-any.whl |
Total release size: 41.0 kB
Release files / rhyme_sdk-0.1.1.tar.gz
| Download URL | rhyme_sdk-0.1.1.tar.gz |
|---|---|
| Size | 18.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b138ec4d59603505e8c5e6ddcf2736690b0093fc30b01a542658d7137c874dcb
|
|
BLAKE2b-256 checksum How to use checksums |
ca21cb3613c545c3142791d474a98b36f626f1231b0f07cb817fed1a7bfd14e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rhyme_sdk-0.1.1-py3-none-any.whl
| Download URL | rhyme_sdk-0.1.1-py3-none-any.whl |
|---|---|
| Size | 22.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6738bc69f44c2453f88bff5a6e4d2156bc4136df1219925dda33f1dd662a921e
|
|
BLAKE2b-256 checksum How to use checksums |
06d9620669105ebf303f350b9703e69356065ff0e968dbbfa5bc0c566d93a5d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for rhyme-sdk 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.