sempera 0.1.0__tar.gz

sempera-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sempera Labs, Inc.
+
+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.

sempera-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: sempera
+Version: 0.1.0
+Summary: The official Python client for the Sempera API: a method for every operation, retries, idempotency keys, paging and webhook verification
+Author-email: "Sempera Labs, Inc." <hello@sempera.org>
+License: MIT
+Project-URL: Homepage, https://github.com/Sempera-AI/sempera-python
+Project-URL: Issues, https://github.com/Sempera-AI/sempera-python/issues
+Keywords: sempera,voice,phone,ai,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sempera
+
+[Documentation](https://docs.sempera.org) | [SDKs](https://docs.sempera.org/sdks) | [OpenAPI document](https://api.sempera.org/openapi.json) | [MIT licence](LICENSE)
+
+The official Python client for the [Sempera](https://sempera.org) API at `https://api.sempera.org`.
+
+* One method for every operation in the public OpenAPI document (`https://api.sempera.org/openapi.json`), generated from it, so the client follows the API.
+* A small hand-written core: bearer-key authentication, typed errors, retries with exponential backoff, automatic idempotency keys, cursor paging and webhook signature verification.
+* Standard library only. Python 3.9 or newer.
+
+## Install
+
+```bash
+pip install sempera
+```
+
+## Quick start
+
+Create an API key in the Sempera App and keep it on your server. Pass it to the constructor, or set `SEMPERA_API_KEY` and omit it.
+
+```python
+from sempera import Sempera
+
+client = Sempera("sempera_sk_example")   # or Sempera() with SEMPERA_API_KEY set
+print(client.get_me())
+```
+
+Methods are named after the operation id in the contract, in snake_case (`list_agents`, `create_call`, `send_sms`). Path and query parameters are named exactly as in the contract. A request body is a plain dict, passed first. Answers are plain dicts.
+
+### Agents
+
+```python
+from sempera import paginate
+
+page = client.list_agents(limit=20)
+for agent in page["data"]:
+    print(agent["id"])
+
+# Or follow every page:
+for agent in paginate(lambda cursor: client.list_agents(limit=100, cursor=cursor)):
+    print(agent["id"])
+
+one = client.get_agent("agt_example")
+```
+
+### Calls
+
+```python
+call = client.create_call(
+    {
+        "agent_id": "agt_example",
+        "mode": "prompt",
+        "phone_number": "+14155550123",
+        "task": "Confirm Friday at 3pm. Ask whether that time still suits.",
+        "consent_basis": "This person asked us to call them about Friday.",
+    },
+    idempotency_key="friday-3pm-ada",
+)
+
+same = client.get_call(call["id"])
+recent = client.list_calls(agent_id="agt_example", limit=10)
+```
+
+### Phone numbers and text messages
+
+```python
+numbers = client.list_phone_numbers(agent_id="agt_example")
+
+client.send_sms({
+    "agent_id": "agt_example",
+    "agent_number": "+14155550100",
+    "user_number": "+14155550123",
+    "agent_message": "Your table is confirmed for Friday at 3pm.",
+    "consent_basis": "This person asked us to text them a confirmation.",
+})
+```
+
+### Conversations
+
+```python
+threads = client.messaging_conversations("agt_example", "sms")
+thread = client.messaging_conversation("agt_example", "sms", "conv_example")
+```
+
+### Knowledge sources
+
+```python
+sources = client.list_knowledge_sources(agent_id="agt_example")
+client.create_text_knowledge_source({
+    "agent_id": "agt_example",
+    "name": "Opening hours",
+    "content": "Open 9 to 5, Monday to Friday.",
+})
+```
+
+### Webhooks
+
+Verify every delivery against the raw request body before you parse it. The helper checks the `X-Sempera-Signature` header (`t=<unix seconds>,v1=<hex HMAC-SHA256 over "<t>." + body>`) in constant time and rejects a timestamp more than 300 seconds from your clock. Answer `400` and process nothing when it raises.
+
+```python
+from sempera import WebhookSignatureError, construct_event
+
+def handle(raw_body: bytes, signature_header: str) -> int:
+    try:
+        event = construct_event("whsec_example", raw_body, signature_header)
+    except WebhookSignatureError:
+        return 400
+    print(event["type"], event["id"])
+    return 200
+```
+
+## Errors
+
+Every refusal raises a typed error carrying `status`, the stable `code`, an optional `reason` and `field`, and the `request_id` to quote to support. Branch on `code` or `reason`, never on the message.
+
+```python
+from sempera import NotFoundError, RateLimitError, SemperaError
+
+try:
+    client.get_agent("agt_missing")
+except NotFoundError as err:
+    print(err.code, err.request_id)
+except RateLimitError as err:
+    print("retry in", err.retry_after)
+except SemperaError as err:
+    print(err.status, err.code, err.reason)
+```
+
+Classes: `ValidationError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `IdempotencyKeyReusedError` (409), `RateLimitError` (429), `ServerError` (5xx) and `ConnectionFailure` (no answer).
+
+## Retries and idempotency
+
+The client retries a `429`, a `502`, a `504`, a `503` with code `service_unavailable` and a dropped connection, two times by default, with exponential backoff and jitter, waiting the `Retry-After` it is sent. Change the count with `max_retries` on the client or on one call. A write is retried only when it carries an idempotency key (generated for you, and reused by every retry) or after a `429`. Pass your own `idempotency_key` to make a retry safe across process restarts.
+
+## Develop
+
+```bash
+python -m unittest discover -s tests
+```
+
+The tests replace the HTTP layer with a scripted fake, so they need no network and no key.
+
+## Licence
+
+MIT. Copyright Sempera Labs, Inc.

sempera-0.1.0/README.md

@@ -0,0 +1,145 @@
+# sempera
+
+[Documentation](https://docs.sempera.org) | [SDKs](https://docs.sempera.org/sdks) | [OpenAPI document](https://api.sempera.org/openapi.json) | [MIT licence](LICENSE)
+
+The official Python client for the [Sempera](https://sempera.org) API at `https://api.sempera.org`.
+
+* One method for every operation in the public OpenAPI document (`https://api.sempera.org/openapi.json`), generated from it, so the client follows the API.
+* A small hand-written core: bearer-key authentication, typed errors, retries with exponential backoff, automatic idempotency keys, cursor paging and webhook signature verification.
+* Standard library only. Python 3.9 or newer.
+
+## Install
+
+```bash
+pip install sempera
+```
+
+## Quick start
+
+Create an API key in the Sempera App and keep it on your server. Pass it to the constructor, or set `SEMPERA_API_KEY` and omit it.
+
+```python
+from sempera import Sempera
+
+client = Sempera("sempera_sk_example")   # or Sempera() with SEMPERA_API_KEY set
+print(client.get_me())
+```
+
+Methods are named after the operation id in the contract, in snake_case (`list_agents`, `create_call`, `send_sms`). Path and query parameters are named exactly as in the contract. A request body is a plain dict, passed first. Answers are plain dicts.
+
+### Agents
+
+```python
+from sempera import paginate
+
+page = client.list_agents(limit=20)
+for agent in page["data"]:
+    print(agent["id"])
+
+# Or follow every page:
+for agent in paginate(lambda cursor: client.list_agents(limit=100, cursor=cursor)):
+    print(agent["id"])
+
+one = client.get_agent("agt_example")
+```
+
+### Calls
+
+```python
+call = client.create_call(
+    {
+        "agent_id": "agt_example",
+        "mode": "prompt",
+        "phone_number": "+14155550123",
+        "task": "Confirm Friday at 3pm. Ask whether that time still suits.",
+        "consent_basis": "This person asked us to call them about Friday.",
+    },
+    idempotency_key="friday-3pm-ada",
+)
+
+same = client.get_call(call["id"])
+recent = client.list_calls(agent_id="agt_example", limit=10)
+```
+
+### Phone numbers and text messages
+
+```python
+numbers = client.list_phone_numbers(agent_id="agt_example")
+
+client.send_sms({
+    "agent_id": "agt_example",
+    "agent_number": "+14155550100",
+    "user_number": "+14155550123",
+    "agent_message": "Your table is confirmed for Friday at 3pm.",
+    "consent_basis": "This person asked us to text them a confirmation.",
+})
+```
+
+### Conversations
+
+```python
+threads = client.messaging_conversations("agt_example", "sms")
+thread = client.messaging_conversation("agt_example", "sms", "conv_example")
+```
+
+### Knowledge sources
+
+```python
+sources = client.list_knowledge_sources(agent_id="agt_example")
+client.create_text_knowledge_source({
+    "agent_id": "agt_example",
+    "name": "Opening hours",
+    "content": "Open 9 to 5, Monday to Friday.",
+})
+```
+
+### Webhooks
+
+Verify every delivery against the raw request body before you parse it. The helper checks the `X-Sempera-Signature` header (`t=<unix seconds>,v1=<hex HMAC-SHA256 over "<t>." + body>`) in constant time and rejects a timestamp more than 300 seconds from your clock. Answer `400` and process nothing when it raises.
+
+```python
+from sempera import WebhookSignatureError, construct_event
+
+def handle(raw_body: bytes, signature_header: str) -> int:
+    try:
+        event = construct_event("whsec_example", raw_body, signature_header)
+    except WebhookSignatureError:
+        return 400
+    print(event["type"], event["id"])
+    return 200
+```
+
+## Errors
+
+Every refusal raises a typed error carrying `status`, the stable `code`, an optional `reason` and `field`, and the `request_id` to quote to support. Branch on `code` or `reason`, never on the message.
+
+```python
+from sempera import NotFoundError, RateLimitError, SemperaError
+
+try:
+    client.get_agent("agt_missing")
+except NotFoundError as err:
+    print(err.code, err.request_id)
+except RateLimitError as err:
+    print("retry in", err.retry_after)
+except SemperaError as err:
+    print(err.status, err.code, err.reason)
+```
+
+Classes: `ValidationError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `IdempotencyKeyReusedError` (409), `RateLimitError` (429), `ServerError` (5xx) and `ConnectionFailure` (no answer).
+
+## Retries and idempotency
+
+The client retries a `429`, a `502`, a `504`, a `503` with code `service_unavailable` and a dropped connection, two times by default, with exponential backoff and jitter, waiting the `Retry-After` it is sent. Change the count with `max_retries` on the client or on one call. A write is retried only when it carries an idempotency key (generated for you, and reused by every retry) or after a `429`. Pass your own `idempotency_key` to make a retry safe across process restarts.
+
+## Develop
+
+```bash
+python -m unittest discover -s tests
+```
+
+The tests replace the HTTP layer with a scripted fake, so they need no network and no key.
+
+## Licence
+
+MIT. Copyright Sempera Labs, Inc.

sempera-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sempera"
+version = "0.1.0"
+description = "The official Python client for the Sempera API: a method for every operation, retries, idempotency keys, paging and webhook verification"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+license = { text = "MIT" }
+authors = [{ name = "Sempera Labs, Inc.", email = "hello@sempera.org" }]
+keywords = ["sempera", "voice", "phone", "ai", "sdk"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/Sempera-AI/sempera-python"
+Issues = "https://github.com/Sempera-AI/sempera-python/issues"
+
+[tool.setuptools]
+packages = ["sempera"]

sempera-0.1.0/sempera/__init__.py

@@ -0,0 +1,29 @@
+"""The Sempera Python SDK. Quick start: https://api.sempera.org/docs/sdks.md."""
+
+from ._generated import API_VERSION, DEFAULT_BASE_URL, ERROR_CODES, OPERATIONS, Operations
+from ._runtime import (
+    AuthenticationError,
+    ConflictError,
+    ConnectionFailure,
+    IdempotencyKeyReusedError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SemperaError,
+    ServerError,
+    ValidationError,
+    paginate,
+)
+from .webhooks import WebhookSignatureError, construct_event, verify_signature
+
+
+class Sempera(Operations):
+    """`Sempera(api_key)` then `client.list_agents()`; one method per operation, named in snake_case."""
+
+
+__all__ = [
+    "API_VERSION", "DEFAULT_BASE_URL", "ERROR_CODES", "OPERATIONS", "Sempera", "paginate",
+    "SemperaError", "ValidationError", "AuthenticationError", "PermissionDeniedError", "NotFoundError",
+    "ConflictError", "IdempotencyKeyReusedError", "RateLimitError", "ServerError", "ConnectionFailure",
+    "WebhookSignatureError", "construct_event", "verify_signature",
+]