Metadata-Version: 2.4
Name: sarj-platform-sdk
Version: 0.4.4
Summary: Python SDK for the Sarj.ai Developer API
Author: Sarj.ai
License: Apache-2.0
Project-URL: repository, https://github.com/sarj-ai/platform.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpcore>=1.0.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.14.1

# Sarj.ai Platform SDK

Typed synchronous and asynchronous Python client for the
[Sarj.ai Developer API](https://platform-docs.sarj.ai).
Requires Python 3.10 or newer.

## Install

```bash
pip install sarj-platform-sdk
```

Or add it to a project with `uv add sarj-platform-sdk`.
Create an API key at [platform.sarj.ai/api-keys](https://platform.sarj.ai/api-keys)
and store it in `SARJ_API_KEY`. Never commit credentials.

## Create and inspect a call

Set `SARJ_SCENARIO_ID` to the scenario UUID copied from your dashboard and
`TEST_PHONE_NUMBER` to a deliberate test destination in E.164 format.
This operation places a real outbound call.

```python
import os

from sarj_platform_sdk import SDK

with SDK(
    api_key_auth=os.environ["SARJ_API_KEY"],
    timeout_ms=10_000,
) as sdk:
    created = sdk.calls.create_call(
        phone_number=os.environ["TEST_PHONE_NUMBER"],
        scenario_id=os.environ["SARJ_SCENARIO_ID"],
        language="ar",
    )
    call = sdk.calls.get_call(call_id=created.data.id)
    print(call.data.id, call.data.status, call.meta.request_id)
```

Creation returns `202 Accepted`; it does not mean the call has completed.
Reports arrive asynchronously and can remain absent. Use a bounded polling
deadline or [webhooks](https://platform-docs.sarj.ai/webhooks) to consume results.
See the [quickstart](https://platform-docs.sarj.ai/getting-started) for the full
lifecycle.

To schedule a call, pass a timezone-aware `datetime` as `scheduled_at`.
Omitting this argument or passing `None` creates an immediate call. Validate
untyped input first: malformed objects such as `{}` can be treated as omitted.

## Async calls and client lifetime

Every generated operation has an `_async` variant. Reuse one client within a
`with SDK(...)` or `async with SDK(...)` context for deterministic cleanup.
Set `SARJ_CALL_ID` to an ID returned by an earlier call.

```python
import asyncio
import os

from sarj_platform_sdk import SDK


async def main():
    async with SDK(
        api_key_auth=os.environ["SARJ_API_KEY"],
        timeout_ms=10_000,
    ) as sdk:
        call = await sdk.calls.get_call_async(call_id=os.environ["SARJ_CALL_ID"])
        print(call.data.status)


asyncio.run(main())
```

## Errors, timeouts, and retries

API errors with a documented shape raise `errors.ErrorResponse`. Branch on
`exception.data.error.type` and retain the request ID for support. When
`exception.data.meta.request_id` is null, use the `X-Request-ID` response header.
Other HTTP failures raise `errors.SDKError`; network failures raise HTTPX
exceptions.

```python
import os
import httpx

from sarj_platform_sdk import SDK, errors

with SDK(api_key_auth=os.environ["SARJ_API_KEY"], timeout_ms=10_000) as sdk:
    try:
        call = sdk.calls.get_call(call_id=os.environ["SARJ_CALL_ID"])
        print(call.data.status)
    except errors.ErrorResponse as exception:
        request_id = exception.data.meta.request_id or exception.headers.get("x-request-id")
        print(exception.data.error.type, request_id)
    except errors.SDKError as exception:
        print(exception.status_code, exception.headers.get("x-request-id"))
    except httpx.RequestError:
        print("Transport failed; reconcile any write before resubmitting.")
```

Set `timeout_ms` for your workload. When omitted, the SDK inherits the HTTPX
client timeout: 5 seconds for SDK-created clients. A supplied client can have a
different default. A method's non-null value overrides the SDK setting; `None`
inherits it. This HTTPX timeout bounds network operations, not total retry
elapsed time, call duration, or a polling loop.

Retries are disabled by default. For a read operation, opt in with the method's
`retries` argument:

```python
from sarj_platform_sdk import SDK
from sarj_platform_sdk.utils import BackoffStrategy, RetryConfig

with SDK(timeout_ms=10_000) as sdk:
    health = sdk.system.get_health(
        retries=RetryConfig(
            strategy="backoff",
            backoff=BackoffStrategy(
                initial_interval=100,
                max_interval=1_000,
                exponent=1.5,
                max_elapsed_time=5_000,
            ),
            retry_connection_errors=False,
        ),
    )
    print(health.data.status)
```

The public health check verifies reachability, not API-key validity.
Opt-in retries cover HTTP `429`, `500`, `502`, `503`, and `504`.
`retry_connection_errors=True` also retries network errors and timeouts.
Use `retries=None` to disable a client's retry policy for one operation.
Backoff uses milliseconds, jitter, and a positive `Retry-After` when present;
its elapsed-time budget is checked after failures and can be exceeded by a
sleep or request. See the [recovery decisions](https://platform-docs.sarj.ai/python-sdk#errors-timeouts-and-retries)
for validation, authorization, call-limit, and scheduling errors.
Do not enable global retries for call creation: after a timeout, an immediate
call may already exist, and retrying can place another call. Keep the returned
call ID when available and reconcile the result before retrying a write.

## Operations

| Resource | Methods | Reference |
| --- | --- | --- |
| `sdk.system` | `get_health` | [Health](https://platform-docs.sarj.ai/api-reference/system/health-check) |
| `sdk.calls` | `create_call`, `get_call` | [Calls](https://platform-docs.sarj.ai/api-reference/calls/place-an-outbound-sarjai-voice-call) |
| `sdk.calls` | `cancel_scheduled_call`, `reschedule_scheduled_call` | [Scheduling](https://platform-docs.sarj.ai/api-reference/calls/move-a-pending-scheduled-sarjai-call-to-a-new-time) |
| `sdk.schedule_configs` | `create_schedule_config` | [Retry policies](https://platform-docs.sarj.ai/api-reference/schedule-configs/create-a-sarjai-schedule-config-retry-policy-for-outbound-calls) |

The recording endpoint redirects to binary audio and is intentionally omitted
from the generated SDK. Use an authenticated HTTP client to resolve
`permanent_recording_url` when you need a fresh download.
Standalone STT/TTS services use their own endpoints and credentials; see
[Speech models](https://platform-docs.sarj.ai/speech-to-text).

## Webhook payloads

Use `sarj_platform_sdk.models.WebhookNotification.model_validate_json(body)` to
parse delivered notification JSON. Host your HTTPS receiver and validate its
configured delivery credential in your application. Follow the
[webhook guide](https://platform-docs.sarj.ai/webhooks) for acknowledgment and
deduplication.

## Support and compatibility

Include the request ID when contacting [support@sarj.ai](mailto:support@sarj.ai).
This SDK is in beta; pin the version used by your application and review
[API documentation](https://platform-docs.sarj.ai/api-reference/overview) before
upgrading.

<!-- These sections are authored; Speakeasy must not restore its defaults. -->
<!-- No Summary [summary] -->
<!-- No Table of Contents [toc] -->
<!-- No SDK Installation [installation] -->
<!-- No IDE Support [idesupport] -->
<!-- No SDK Example Usage [usage] -->
<!-- No Authentication [security] -->
<!-- No Available Resources and Operations [operations] -->
<!-- No Retries [retries] -->
<!-- No Error Handling [errors] -->
<!-- No Server Selection [server] -->
<!-- No Custom HTTP Client [http-client] -->
<!-- No Resource Management [resource-management] -->
<!-- No Debugging [debug] -->
<!-- Placeholder for Future Speakeasy SDK Sections -->
