cherami 0.1.0__tar.gz

cherami-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.mypy_cache/
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.generation.json
+.env
+.env.*

cherami-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+For a bug report, include a minimal reproduction, Python and SDK versions, the operation, and a request ID when available. Omit API keys, mail bodies and private attachments. Send security issues or private account questions to hello@cherami.to rather than a public issue.
+
+Use Python 3.11+, uv and Bun. Applications consuming the package need only Python and its runtime dependencies.
+
+```sh
+uv sync --locked
+bun scripts/generate.mts
+```
+
+The selected `openapi.json` and `operations.json` are the generation inputs. Discuss contract changes or new operations with a maintainer before implementing them; behavior must agree with the service's [HTTP reference](https://cherami.to/docs/api). Do not edit `models.py`, `_operations.py` or `_routes.py` directly. The generator produces static `TypedDict` models and method/pagination signatures; it does not add runtime response coercion. A narrow receipt-refinement normalization works around the model generator's conflicting TypedDict inheritance while leaving the public snapshot unchanged.
+
+Keep transport, serialization, errors, pagination and send-recovery policy shared between sync and async clients. Only HTTPX I/O and iterator syntax differ. Preserve omitted versus null values, original file bytes, request IDs and accepted/rejected/unknown outcomes. No automatic retries or redirects. A broken response or cancellation cannot establish that a write was rolled back.
+
+Use focused manual checks with a substituted HTTPX transport for fault paths. Real requests require an appropriately authorized account and workflow; never send mail or mutate an inbox merely to check an example. Do not commit credentials, mail, recovery records or private operation material. The runnable examples explain private file handling and explicit sending.
+
+## Distribution
+
+`uv build` prepares a wheel and source archive in `dist/`. Inspect their contents and consume the wheel in an isolated environment before release. The wheel contains `cherami` source, `py.typed`, license and package metadata, not generation tools or workspace dependencies. The source archive includes everything needed for standalone generation, including `uv.lock`.
+
+Maintainers publish releases manually. Verify that the source archive regenerates independently and that source and package metadata agree. Publish the reviewed artifact rather than rebuilding an unchecked tree; update installation guidance alongside package availability. No registry credential is required for local development.
+
+In a pull request, explain the problem, proposed change and what you checked. Update examples or documentation when usage changes, and distinguish local fixture results from live service behavior.

cherami-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cherami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cherami-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: cherami
+Version: 0.1.0
+Summary: Official Cherami HTTP client: inboxes, correspondence, drafts, attachments and conversations.
+Project-URL: Homepage, https://cherami.to
+Project-URL: Documentation, https://cherami.to/docs/guides/python
+Project-URL: Repository, https://github.com/cherami-mail/cherami-python
+Project-URL: Issues, https://github.com/cherami-mail/cherami-python/issues
+Author: Cherami
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<0.29,>=0.28.1
+Description-Content-Type: text/markdown
+
+# Cherami Python SDK
+
+The official Python client for [Cherami](https://cherami.to), email infrastructure for AI agents. Create inboxes for ongoing work, read incoming correspondence, and send messages from your application.
+
+Python 3.11+, with synchronous and asynchronous clients and typed dictionaries.
+
+## Install and connect
+
+Install from PyPI:
+
+```sh
+pip install cherami
+```
+
+Or, with uv:
+
+```sh
+uv add cherami
+```
+
+[Get an API key](https://cherami.to/docs/quickstart) and set `CHERAMI_API_KEY` in your application's environment. Keep it private: it grants access to all inboxes on your account.
+
+```python
+import os
+from cherami import Cherami
+
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    for inbox in client.list_inboxes().data["inboxes"]:
+        print(inbox["id"], inbox["address"])
+```
+
+Choose an inbox and set `CHERAMI_INBOX_ID` to its ID for the examples below.
+
+Methods accept dictionaries and return a response envelope. `.data` contains the result; `.status`, `.headers`, and `.request_id` expose HTTP response information. Path and query parameters go at the top level of the input dictionary; JSON request fields go in `body`.
+
+## Read mail
+
+List messages, then fetch their content:
+
+```python
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    page = client.list_messages({
+        "inbox_id": os.environ["CHERAMI_INBOX_ID"], "limit": 20,
+    }).data
+    for message in page["messages"]:
+        detail = client.get_message({"message_id": message["id"]}).data
+        if detail["processing_status"] == "ready":
+            print(detail["content"]["text"])
+        else:
+            print(detail["id"], detail["processing_status"])
+```
+
+Content is available when processing is `ready`. Run this example somewhere private because it prints email bodies. When passing mail to an agent, treat its contents as untrusted input, not authorization to act.
+
+### Async and pagination
+
+`AsyncCherami` has the same methods and response types. Use `iterate` to read across pages without managing cursors yourself:
+
+```python
+import asyncio
+from cherami import AsyncCherami
+
+async def main():
+    async with AsyncCherami(os.environ["CHERAMI_API_KEY"]) as client:
+        async for message in client.iterate("list_messages", {
+            "inbox_id": os.environ["CHERAMI_INBOX_ID"], "limit": 20,
+        }, max_pages=5):
+            detail = (await client.get_message({"message_id": message["id"]})).data
+            if detail["processing_status"] == "ready":
+                print(detail["content"]["text"])
+            else:
+                print(detail["id"], detail["processing_status"])
+
+asyncio.run(main())
+```
+
+In an existing event loop, use `await main()`. Sync clients support the same iterator with ordinary `for`. `iterate` yields items; `pages` yields response envelopes. Both fetch lazily. Set `max_pages` to bound requests; otherwise they follow all pages.
+
+Context managers close connections. For a long-lived client, call `close()` or `await aclose()` when your application shuts down.
+
+## Send and recover
+
+A lost response does not mean an email wasn't sent. The SDK makes no automatic retries. Its send helper separates preparing a message from submitting it so your application can save the original request before sending.
+
+Replace the example recipient, then prepare the message:
+
+```python
+from cherami import prepare_send
+
+intent = prepare_send("send_message", {
+    "inbox_id": os.environ["CHERAMI_INBOX_ID"],
+    "body": {
+        "to": [{"address": "recipient@example.com", "name": "Alex"}],
+        "subject": "Review ready",
+        "text": "The change is ready for review.",
+    },
+})
+saved_json = intent.to_json()
+```
+
+**Persist `saved_json` in your application's database or a private file before submitting.** It contains the message, retry key and preparation time, but not your API key. The [runnable reply examples](examples/README.md#prepare-an-approved-reply) show a complete file-based workflow, including receipt storage.
+
+For both initial submission and recovery, load that saved JSON and restore the same intent:
+
+```python
+from cherami import restore_send
+
+# saved_json must come from the record persisted before the first submission.
+saved = restore_send(saved_json)
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    result = client.submit(saved)
+    receipt = {
+        "data": result.data,
+        "status": result.status,
+        "request_id": result.request_id,
+    }
+    # Persist this receipt without replacing earlier receipts for the intent.
+```
+
+Read `result.data["message"]["status"]` to distinguish the outcome:
+
+| Outcome | Meaning |
+| --- | --- |
+| `accepted` | The provider accepted submission. This is not proof of delivery. |
+| `rejected` | The provider explicitly rejected submission. |
+| `unknown` | Submission may have succeeded. Recover using the saved intent, not a new send. |
+
+These outcomes are data, not exceptions. Preserve every returned receipt: when `outcome_persisted` is false, it may contain an outcome that later reads do not yet show. A failed local save does not undo sending.
+
+The helper refuses submission after **23 hours and 59 minutes from preparation**. Restoring an intent does not extend that window. After expiry, inspect sent resources rather than preparing a replacement for an uncertain send. Recovery retrieves the outcome; it does not resume provider submission.
+
+The helper also supports `reply_message`, `reply_all_message`, and `forward_message`. Direct send methods leave retry-key and recovery-window management to your application. Drafts use `send_draft` with separate same-draft protection. See the [sending guide](https://cherami.to/docs/guides/sending) and [draft guide](https://cherami.to/docs/guides/drafts) for those workflows.
+
+## Handle errors
+
+```python
+from cherami import CheramiApiError, CheramiTransportError
+
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    try:
+        inboxes = client.list_inboxes().data
+    except CheramiApiError as error:
+        print(error.status, error.code, error.request_id)
+    except CheramiTransportError:
+        # No usable API response was received.
+        raise
+```
+
+API errors also expose `.body`, `.headers`, and `.retry_after`. Transport failures raise `CheramiTransportError`; async cancellation propagates normally. For writes, neither a transport failure nor cancellation proves the operation was rolled back. Use the saved-intent workflow above for uncertain sends.
+
+Clients use HTTPX with a default 60-second inactivity timeout per network operation. Pass `timeout` to a client or method to change it, or `None` to disable it. Requests do not automatically retry or follow redirects.
+
+## More workflows
+
+The SDK supports inboxes, received and sent mail, replies, forwarding, drafts, labels, conversations, policy inspection and attachment downloads.
+
+- [Runnable examples](examples/README.md): read mail, prepare a reply, and submit or recover it.
+- [Python guide](https://cherami.to/docs/guides/python): client configuration, attachments and download handling.
+- [HTTP reference](https://cherami.to/docs/api): input fields and response contracts. Named Python types are available from `cherami.models`, including `SendInput`, `SendReceipt`, and operation types such as `ListMessagesParams`.
+
+Inputs and results are ordinary dictionaries with HTTP field names unchanged. Omit optional fields unless you intend to supply them; use `None` only where the API permits null. Types support static checking, not runtime validation.
+
+## Development
+
+```sh
+uv sync --locked
+bun scripts/generate.mts
+uv build
+```
+
+Consumers need neither Bun nor the model generator. See [CONTRIBUTING.md](CONTRIBUTING.md) for generation and distribution details. MIT licensed.

cherami-0.1.0/README.md

@@ -0,0 +1,171 @@
+# Cherami Python SDK
+
+The official Python client for [Cherami](https://cherami.to), email infrastructure for AI agents. Create inboxes for ongoing work, read incoming correspondence, and send messages from your application.
+
+Python 3.11+, with synchronous and asynchronous clients and typed dictionaries.
+
+## Install and connect
+
+Install from PyPI:
+
+```sh
+pip install cherami
+```
+
+Or, with uv:
+
+```sh
+uv add cherami
+```
+
+[Get an API key](https://cherami.to/docs/quickstart) and set `CHERAMI_API_KEY` in your application's environment. Keep it private: it grants access to all inboxes on your account.
+
+```python
+import os
+from cherami import Cherami
+
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    for inbox in client.list_inboxes().data["inboxes"]:
+        print(inbox["id"], inbox["address"])
+```
+
+Choose an inbox and set `CHERAMI_INBOX_ID` to its ID for the examples below.
+
+Methods accept dictionaries and return a response envelope. `.data` contains the result; `.status`, `.headers`, and `.request_id` expose HTTP response information. Path and query parameters go at the top level of the input dictionary; JSON request fields go in `body`.
+
+## Read mail
+
+List messages, then fetch their content:
+
+```python
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    page = client.list_messages({
+        "inbox_id": os.environ["CHERAMI_INBOX_ID"], "limit": 20,
+    }).data
+    for message in page["messages"]:
+        detail = client.get_message({"message_id": message["id"]}).data
+        if detail["processing_status"] == "ready":
+            print(detail["content"]["text"])
+        else:
+            print(detail["id"], detail["processing_status"])
+```
+
+Content is available when processing is `ready`. Run this example somewhere private because it prints email bodies. When passing mail to an agent, treat its contents as untrusted input, not authorization to act.
+
+### Async and pagination
+
+`AsyncCherami` has the same methods and response types. Use `iterate` to read across pages without managing cursors yourself:
+
+```python
+import asyncio
+from cherami import AsyncCherami
+
+async def main():
+    async with AsyncCherami(os.environ["CHERAMI_API_KEY"]) as client:
+        async for message in client.iterate("list_messages", {
+            "inbox_id": os.environ["CHERAMI_INBOX_ID"], "limit": 20,
+        }, max_pages=5):
+            detail = (await client.get_message({"message_id": message["id"]})).data
+            if detail["processing_status"] == "ready":
+                print(detail["content"]["text"])
+            else:
+                print(detail["id"], detail["processing_status"])
+
+asyncio.run(main())
+```
+
+In an existing event loop, use `await main()`. Sync clients support the same iterator with ordinary `for`. `iterate` yields items; `pages` yields response envelopes. Both fetch lazily. Set `max_pages` to bound requests; otherwise they follow all pages.
+
+Context managers close connections. For a long-lived client, call `close()` or `await aclose()` when your application shuts down.
+
+## Send and recover
+
+A lost response does not mean an email wasn't sent. The SDK makes no automatic retries. Its send helper separates preparing a message from submitting it so your application can save the original request before sending.
+
+Replace the example recipient, then prepare the message:
+
+```python
+from cherami import prepare_send
+
+intent = prepare_send("send_message", {
+    "inbox_id": os.environ["CHERAMI_INBOX_ID"],
+    "body": {
+        "to": [{"address": "recipient@example.com", "name": "Alex"}],
+        "subject": "Review ready",
+        "text": "The change is ready for review.",
+    },
+})
+saved_json = intent.to_json()
+```
+
+**Persist `saved_json` in your application's database or a private file before submitting.** It contains the message, retry key and preparation time, but not your API key. The [runnable reply examples](examples/README.md#prepare-an-approved-reply) show a complete file-based workflow, including receipt storage.
+
+For both initial submission and recovery, load that saved JSON and restore the same intent:
+
+```python
+from cherami import restore_send
+
+# saved_json must come from the record persisted before the first submission.
+saved = restore_send(saved_json)
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    result = client.submit(saved)
+    receipt = {
+        "data": result.data,
+        "status": result.status,
+        "request_id": result.request_id,
+    }
+    # Persist this receipt without replacing earlier receipts for the intent.
+```
+
+Read `result.data["message"]["status"]` to distinguish the outcome:
+
+| Outcome | Meaning |
+| --- | --- |
+| `accepted` | The provider accepted submission. This is not proof of delivery. |
+| `rejected` | The provider explicitly rejected submission. |
+| `unknown` | Submission may have succeeded. Recover using the saved intent, not a new send. |
+
+These outcomes are data, not exceptions. Preserve every returned receipt: when `outcome_persisted` is false, it may contain an outcome that later reads do not yet show. A failed local save does not undo sending.
+
+The helper refuses submission after **23 hours and 59 minutes from preparation**. Restoring an intent does not extend that window. After expiry, inspect sent resources rather than preparing a replacement for an uncertain send. Recovery retrieves the outcome; it does not resume provider submission.
+
+The helper also supports `reply_message`, `reply_all_message`, and `forward_message`. Direct send methods leave retry-key and recovery-window management to your application. Drafts use `send_draft` with separate same-draft protection. See the [sending guide](https://cherami.to/docs/guides/sending) and [draft guide](https://cherami.to/docs/guides/drafts) for those workflows.
+
+## Handle errors
+
+```python
+from cherami import CheramiApiError, CheramiTransportError
+
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    try:
+        inboxes = client.list_inboxes().data
+    except CheramiApiError as error:
+        print(error.status, error.code, error.request_id)
+    except CheramiTransportError:
+        # No usable API response was received.
+        raise
+```
+
+API errors also expose `.body`, `.headers`, and `.retry_after`. Transport failures raise `CheramiTransportError`; async cancellation propagates normally. For writes, neither a transport failure nor cancellation proves the operation was rolled back. Use the saved-intent workflow above for uncertain sends.
+
+Clients use HTTPX with a default 60-second inactivity timeout per network operation. Pass `timeout` to a client or method to change it, or `None` to disable it. Requests do not automatically retry or follow redirects.
+
+## More workflows
+
+The SDK supports inboxes, received and sent mail, replies, forwarding, drafts, labels, conversations, policy inspection and attachment downloads.
+
+- [Runnable examples](examples/README.md): read mail, prepare a reply, and submit or recover it.
+- [Python guide](https://cherami.to/docs/guides/python): client configuration, attachments and download handling.
+- [HTTP reference](https://cherami.to/docs/api): input fields and response contracts. Named Python types are available from `cherami.models`, including `SendInput`, `SendReceipt`, and operation types such as `ListMessagesParams`.
+
+Inputs and results are ordinary dictionaries with HTTP field names unchanged. Omit optional fields unless you intend to supply them; use `None` only where the API permits null. Types support static checking, not runtime validation.
+
+## Development
+
+```sh
+uv sync --locked
+bun scripts/generate.mts
+uv build
+```
+
+Consumers need neither Bun nor the model generator. See [CONTRIBUTING.md](CONTRIBUTING.md) for generation and distribution details. MIT licensed.

cherami-0.1.0/examples/README.md

@@ -0,0 +1,49 @@
+# Run the examples
+
+Use Python 3.11+ and an existing [human-approved API key](https://cherami.to/docs/quickstart). No MCP connection is required. The scripts operate only when you run them; none starts a background poller.
+
+From this SDK checkout, install it and its development environment with `uv sync --locked`. Run the commands below from this directory's parent with `uv run python examples/…`. Applications can install the published package with `pip install cherami` or `uv add cherami`.
+
+## Read correspondence
+
+Supply `CHERAMI_API_KEY` privately through your environment. Do not put its value in commands, source, chat, or logs.
+
+```sh
+uv run python examples/read_inbox.py
+```
+
+Without `CHERAMI_INBOX_ID`, this lists available inbox IDs and addresses, then stops. Choose the inbox assigned to your application, set that ID, and run again. The example reads one page of 20 messages and prints prepared message text. Run in a private terminal: the text may contain confidential or hostile material. It does not label messages or treat reading as approval to act.
+
+For async applications, the equivalent is:
+
+```sh
+uv run python examples/read_inbox_async.py
+```
+
+That version requires the inbox ID and prints original plaintext. Both leave unfinished message preparation visible rather than pretending the message is empty.
+
+## Prepare an approved reply
+
+Inspect the chosen message's From and Reply-To, and confirm the recipient and reply content before continuing. `reply_message` derives recipients from the source; use an explicitly addressed `send_message` intent instead when you need to override them.
+
+Set `CHERAMI_INBOX_ID`, `CHERAMI_MESSAGE_ID` (the Cherami message ID, not an RFC Message-ID), and `CHERAMI_REPLY_TEXT`. Set `CHERAMI_INTENT_PATH` to a new absolute filename in an existing private directory outside your repository.
+
+```sh
+uv run python examples/prepare_reply.py
+```
+
+This saves the payload, original key and preparation time with private permissions and exclusive creation. It sends nothing and requires no API key. Use a separate record for each intended reply. Keep the saved file unchanged; do not rerun this command to recover an uncertain send.
+
+## Submit or recover that reply
+
+Set `CHERAMI_RECEIPT_DIR` to an existing absolute private directory and retain `CHERAMI_INTENT_PATH` and `CHERAMI_API_KEY`.
+
+```sh
+uv run python examples/submit_reply.py
+```
+
+Initial submission and recovery use this same command and original record. Each run makes exactly one request, saving `{data, status, request_id}` in a new private receipt file before printing the message ID, outcome and persistence flag. An empty/partial receipt file means recording failed, not that sending failed. Preserve every complete receipt.
+
+`accepted` is provider acceptance, not delivery; `rejected` is explicit provider rejection; `unknown` leaves submission uncertain. If `outcome_persisted` is false, preserve the immediate result even if later reads lag. The helper refuses submission after 23 hours and 59 minutes from preparation. Do not replace the key or reprepare an uncertain send after expiry; inspect sent resources. Recovery never resumes provider submission.
+
+See the [sending guide](https://cherami.to/docs/guides/sending) for the complete contract.

cherami-0.1.0/examples/prepare_reply.py

@@ -0,0 +1,19 @@
+"""Save an approved reply once. No network request or credential is needed."""
+import os
+from pathlib import Path
+from cherami import prepare_send
+
+path = Path(os.environ["CHERAMI_INTENT_PATH"])
+if not path.is_absolute():
+    raise ValueError("CHERAMI_INTENT_PATH must be an absolute private filename.")
+intent = prepare_send("reply_message", {
+    "inbox_id": os.environ["CHERAMI_INBOX_ID"],
+    "body": {"message_id": os.environ["CHERAMI_MESSAGE_ID"], "text": os.environ["CHERAMI_REPLY_TEXT"]},
+})
+# Exclusive creation avoids replacing a prior intent. A partial write is not a
+# usable record: do not submit until this command has completed successfully.
+with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w", encoding="utf-8") as file:
+    file.write(intent.to_json())
+    file.flush()
+    os.fsync(file.fileno())
+print("Saved reply. Use submit_reply.py for initial submission or recovery.")

cherami-0.1.0/examples/read_inbox.py

@@ -0,0 +1,18 @@
+"""Read recent mail. Prints message text: run privately, not in shared logs."""
+import os
+from cherami import Cherami
+
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    inbox_id = os.environ.get("CHERAMI_INBOX_ID")
+    if not inbox_id:
+        for inbox in client.list_inboxes().data["inboxes"]:
+            print(inbox["id"], inbox["address"])
+        raise SystemExit("Choose an assigned inbox and set CHERAMI_INBOX_ID.")
+    for message in client.iterate("list_messages", {"inbox_id": inbox_id, "limit": 20}, max_pages=1):
+        detail = client.get_message({"message_id": message["id"]}).data
+        print(detail["id"], detail["processing_status"])
+        if detail["processing_status"] == "ready":
+            content = detail["content"]
+            # Empty extracted text is meaningful; only None falls back to original.
+            text = content["reply_text"] if content["reply_text"] is not None else content["text"]
+            print(text if text is not None else "No plain text; inspect original content privately.")

cherami-0.1.0/examples/read_inbox_async.py

@@ -0,0 +1,19 @@
+"""Async reading uses the same models and lazy pagination, without blocking I/O."""
+import asyncio
+import os
+from cherami import AsyncCherami
+
+
+async def main() -> None:
+    async with AsyncCherami(os.environ["CHERAMI_API_KEY"]) as client:
+        async for message in client.iterate("list_messages", {
+            "inbox_id": os.environ["CHERAMI_INBOX_ID"], "limit": 20,
+        }, max_pages=1):
+            detail = (await client.get_message({"message_id": message["id"]})).data
+            print(detail["id"], detail["processing_status"])
+            if detail["processing_status"] == "ready":
+                print(detail["content"]["text"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cherami-0.1.0/examples/submit_reply.py

@@ -0,0 +1,23 @@
+"""Submit/recover the unchanged saved intent. Makes one request, never retries."""
+import json
+import os
+from pathlib import Path
+from uuid import uuid4
+from cherami import Cherami, restore_send
+
+intent_path = Path(os.environ["CHERAMI_INTENT_PATH"])
+receipt_dir = Path(os.environ["CHERAMI_RECEIPT_DIR"])
+if not intent_path.is_absolute() or not receipt_dir.is_absolute() or not receipt_dir.is_dir():
+    raise ValueError("Use an absolute intent filename and existing private receipt directory.")
+intent = restore_send(intent_path.read_text(encoding="utf-8"))
+with Cherami(os.environ["CHERAMI_API_KEY"]) as client:
+    # Open the destination before any send. Every response gets its own receipt;
+    # a later unknown replay must not overwrite earlier provider acceptance.
+    path = receipt_dir / f"receipt-{uuid4()}.json"
+    with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w", encoding="utf-8") as file:
+        result = client.submit(intent)
+        json.dump({"data": result.data, "status": result.status, "request_id": result.request_id}, file)
+        file.flush()
+        os.fsync(file.fileno())
+        print(result.data["message"]["id"], result.data["message"]["status"], result.data["outcome_persisted"])
+# File-write failure does not undo a send. Empty/partial files are not receipts.