Metadata-Version: 2.4
Name: sema4ai-api-client
Version: 3.0.0
Summary: Generated Python client for the Sema4.ai API
Author-email: "Sema4.ai Engineering" <engineering@sema4.ai>
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<0.29.0,>=0.23.0
Requires-Dist: python-dateutil<3.0.0,>=2.8.0
Description-Content-Type: text/markdown

# sema4ai_api_client

A client library for accessing the Sema4.ai API.

## Usage

First, create a client:

```python
from sema4ai_api_client import Client

client = Client(base_url="https://api.example.com")
```

If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:

```python
from sema4ai_api_client import AuthenticatedClient

client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
```

Now call your endpoint and use your models:

```python
from sema4ai_api_client.models.my_data_model import MyDataModel
from sema4ai_api_client.api.my_tag import get_my_data_model
from sema4ai_api_client.types import Response

with client as client:
    my_data: MyDataModel | None = get_my_data_model.sync(client=client)
    # or if you need more info (e.g. status_code)
    response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
```

Or do the same thing with an async version:

```python
from sema4ai_api_client.models.my_data_model import MyDataModel
from sema4ai_api_client.api.my_tag import get_my_data_model
from sema4ai_api_client.types import Response

async with client as client:
    my_data: MyDataModel | None = await get_my_data_model.asyncio(client=client)
    response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
```

By default, HTTPS calls verify TLS certificates. You can provide a custom certificate bundle:

```python
client = AuthenticatedClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl="/path/to/certificate_bundle.pem",
)
```

You can also disable certificate validation, but this is a security risk:

```python
client = AuthenticatedClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl=False,
)
```

Things to know:

1. Every path/method combo becomes a Python module with four functions:
   1. `sync`: Blocking request that returns parsed data (if successful) or `None`
   1. `sync_detailed`: Blocking request that always returns a `Response`, with `parsed` set when successful
   1. `asyncio`: Like `sync`, but async
   1. `asyncio_detailed`: Like `sync_detailed`, but async
1. All path/query params and request bodies become function arguments.
1. If an endpoint has tags, the first tag is used as the API module name.
1. Endpoints without tags are available under `sema4ai_api_client.api.default`.

## Advanced customizations

You can customize the underlying `httpx.Client` / `httpx.AsyncClient` with `httpx_args`:

```python
from sema4ai_api_client import Client

def log_request(request):
    print(f"Request event hook: {request.method} {request.url} - Waiting for response")

def log_response(response):
    request = response.request
    print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")

client = Client(
    base_url="https://api.example.com",
    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
)
```

Or set an httpx client directly (this overrides shared settings like `base_url` unless you set them again):

```python
import httpx
from sema4ai_api_client import Client

client = Client(base_url="https://api.example.com")
client.set_httpx_client(httpx.Client(base_url="https://api.example.com", proxy="http://localhost:8030"))
```

## Regenerate client

From the repo root:

```bash
make update-api-client
```

Or manually from `packages/api-client`:

```bash
uvx openapi-python-client generate \
  --path "../../workroom/packages/agent-server-interface/public.openapi.json" \
  --config "openapi-client-config.yaml" \
  --meta none \
  --output-path "sema4ai_api_client"
```

## Build

```bash
uv build
```

Install locally into another project:

```bash
uv pip install dist/sema4ai_api_client-*.whl
```

## Release

Releases are published to PyPI automatically via GitHub Actions using [trusted publishers](https://docs.pypi.org/trusted-publishers/) (OIDC). No API tokens are needed.

### Steps

1. Update the version in `pyproject.toml`.
2. Commit and push the version change to `main`.
3. Create and push a tag matching the pattern `sema4ai-api-client-<version>`:

   ```bash
   # Or use the invoke task which validates the branch and version:
   pip install invoke && invoke make-release
   ```

   Alternatively, tag manually:

   ```bash
   git tag -a sema4ai-api-client-3.0.0 -m "Release 3.0.0"
   git push origin sema4ai-api-client-3.0.0
   ```

4. The `api-client-release.yml` workflow picks up the tag, builds the package, and publishes it to PyPI.

### Prerequisites

A [trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) must be configured on PyPI for the `sema4ai-api-client` project:

- **Owner:** `Sema4AI`
- **Repository:** `moonraker`
- **Workflow:** `api-client-release.yml`
- **Environment:** _(leave blank)_
