> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawa-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Official Python SDK for the Pawa AI API — install, authenticate, and call every endpoint from models to transcribe.

The **Pawa AI Python SDK** (`pawa-ai`) is the official client for the Pawa AI API. It wraps chat, models, voice, embeddings, document parsing, agents, knowledge bases, and transcription behind a typed Python interface — with sync and async clients, streaming helpers, and automatic retries.

Use it when you want to call the same surface documented in the [API reference](/api-reference/introduction) without hand-writing HTTP requests.

## Requirements

* Python **3.9+**
* A Pawa AI API key from the [Builders Dashboard](https://builder.pawa-ai.com/dashboard?page=keys)

## Installation

```bash theme={null}
pip install pawa-ai
```

## Authentication

Set your API key as an environment variable (recommended):

```bash theme={null}
export PAWA_AI_API_KEY="your_api_key_here"
```

Then create a client:

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()
```

Or pass the key explicitly:

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI(api_key="your_api_key_here")
```

## Quick example

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "user",
            "content": [{"type": "text", "text": "Habari yako?"}],
        }
    ],
    stream=False,
)

print(response["data"]["request"][0]["message"]["content"])
```

## API coverage

| Resource   | SDK path                        | Methods                                                         |
| ---------- | ------------------------------- | --------------------------------------------------------------- |
| Models     | `client.models`                 | `list`, `retrieve`                                              |
| Chat       | `client.chat`                   | `create`, `completions`                                         |
| Voice      | `client.voice`                  | `text_to_speech.create`, `speech_to_text.create`                |
| Vectors    | `client.vectors`                | `create`, `embeddings`                                          |
| Documents  | `client.documents`              | `parse`                                                         |
| Agents     | `client.agents`                 | `create`, `update`, `delete`, `list`, `retrieve`, `chat.create` |
| Storage    | `client.storage.knowledge_base` | CRUD, `list_files`, `semantic_retrieval`                        |
| Transcribe | `client.transcribe.workspaces`  | CRUD + transcription management                                 |

Chat and agent chat support both **non-streaming** (`stream=False`) and **streaming** (`stream=True`) responses.

## Source & package

* **PyPI:** [pypi.org/project/pawa-ai](https://pypi.org/project/pawa-ai/#description)
* **GitHub:** [github.com/Sartify/pawa-ai-python](https://github.com/Sartify/pawa-ai-python)

<CardGroup cols={2}>
  <Card title="PyPI package" icon="box" href="https://pypi.org/project/pawa-ai/#description">
    Install with pip and read the package description.
  </Card>

  <Card title="Source on GitHub" icon="github" href="https://github.com/Sartify/pawa-ai-python">
    Browse the SDK source, examples, and issue tracker.
  </Card>
</CardGroup>