Metadata-Version: 2.4
Name: facesign-sdk
Version: 0.0.3
Summary: A Python client for the FaceSign API.
Keywords: facesign,sdk,client,api
Author: FaceSign
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Dist: httpx (>=0.27,<1.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Project-URL: Repository, https://github.com/facesignai/FaceSign.SDK
Description-Content-Type: text/markdown

# facesign-sdk

A Python client for the [FaceSign](https://facesign.ai) API.

Asynchronous (built on [`httpx`](https://www.python-httpx.org/)) and typed (ships `py.typed`).

## Requirements

- Python **3.12+**
- `httpx`, `pydantic` (installed automatically)

## Installation

```sh
pip install facesign-sdk
```

## Authentication

The SDK resolves your API key via `Credentials.default()`, which checks, in order:

1. The `FACESIGN_API_KEY` environment variable
2. `~/.config/facesign/$FACESIGN_PROJECT/api_key`

The base URL is resolved from the `FACESIGN_API_URL` environment variable or
`~/.config/facesign/$FACESIGN_PROJECT/config.json` (`api_url`), defaulting to
`https://api.facesign.ai`. Pass it explicitly to the client below.

## Quickstart

```python
import asyncio
from facesign_sdk.client import Client, ClientOptions
from facesign_sdk.credentials import Credentials


async def main() -> None:
    client = Client(
        ClientOptions(
            creds=Credentials.default(),
            base_url="https://api.facesign.ai",
        )
    )

    result = await client.list_users()
    if result.status_code == 200 and result.data is not None:
        print(result.data)
    else:
        print(result.error or result.response_body)


asyncio.run(main())
```

Every method returns a `ClientResponse[TData, TError]` with:

- `status_code: int`
- `data: TData | None` — the parsed response body on success
- `error: TError | None` — a parsed `ErrorResponse` on failure
- `response_body: str | None` — the raw response body

## Available methods

| Method | Description |
| --- | --- |
| `list_users()` | List users |
| `get_user_api_keys(user_id)` | List a user's API keys |
| `create_user_api_key(user_id, body)` | Create a user API key |
| `revoke_user_api_key(id, user_id)` | Revoke a user API key |
| `list_avatars()` | List avatars |
| `create_avatar(body)` | Create an avatar |
| `get_avatar(id)` | Get an avatar |
| `update_avatar(id, body)` | Update an avatar |
| `delete_avatar(id)` | Delete an avatar |
| `create_session(body)` | Create a session |
| `start_session()` | Start a session |
| `create_session_prop(id, body)` | Create a session prop |
| `get_session_detail(session_id)` | Get session detail |
| `list_session_utterances(session_id)` | List session utterances |
| `get_demo_report(session_id)` | Get a demo report |

Request/response models are available in `facesign_sdk.client` (e.g.
`from facesign_sdk.client import ListUsersResponse`).

## Development

This package is generated from the OpenAPI spec via [`uni`](../uni.toml). To
regenerate the client, run `make gen` from the repository root (it writes to
`facesign_sdk/client.py`).

To build a distribution locally:

```sh
python -m build        # produces dist/*.whl and dist/*.tar.gz
```

