Initial commit: Pawa AI Python SDK with CI/CD.

Add the official SDK for chat, voice, embeddings, agents, and related APIs,
with typed response models, retry/backoff, streaming helpers, and GitHub Actions.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: innocent-charles

.env.example

@@ -0,0 +1 @@
+PAWA_AI_API_KEY=your_api_key_here

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Test plan
+
+- [ ] `pytest` passes locally
+- [ ] `ruff check src tests` passes locally

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Ruff
+        run: ruff check src tests
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Run tests
+        run: pytest -q --cov=pawa_ai --cov-report=term-missing
+        env:
+          PAWA_AI_API_KEY: test-key-for-ci
+
+      - name: Upload coverage (3.12 only)
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: .coverage
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Upload to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pawa-ai
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.swp
+.DS_Store
+.idea/
+.vscode/

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to pawa-ai-python
+
+Thanks for helping improve the official Pawa AI Python SDK.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Checks before opening a PR
+
+```bash
+ruff check src tests
+pytest -q
+python -m build
+```
+
+## CI
+
+GitHub Actions runs on every push and pull request to `main`:
+
+- **Lint** — `ruff check`
+- **Test** — `pytest` on Python 3.9–3.13
+- **Build** — validates the package builds cleanly
+
+## Releases
+
+1. Update the version in `pyproject.toml` and `src/pawa_ai/__init__.py`
+2. Create a GitHub Release with a tag like `v0.2.0`
+3. The **Publish to PyPI** workflow uploads the package automatically
+
+Configure the `pypi` environment in GitHub with [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) for `pawa-ai`.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sartify Company Limited
+
+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.

README.md

@@ -0,0 +1,174 @@
+# Pawa AI Python SDK
+
+[![CI](https://github.com/Sartify/pawa-ai-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Sartify/pawa-ai-python/actions/workflows/ci.yml)
+
+Official Python library for the [Pawa AI API](https://docs.pawa-ai.com).
+
+Pawa AI provides African-built small language models for chat, voice, embeddings, document parsing, agents, and knowledge bases.
+
+## Installation
+
+```bash
+pip install pawa-ai
+```
+
+## Quickstart
+
+Set your API key:
+
+```bash
+export PAWA_AI_API_KEY="your_api_key_here"
+```
+
+Get your key from the [Builders Dashboard](https://builder.pawa-ai.com/dashboard?page=keys).
+
+### Chat
+
+```python
+from pawa_ai import PawaAI
+
+client = PawaAI()
+
+response = client.chat.create(
+    model="pawa-v1-ember-20240924",
+    messages=[
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": "Hello! How can I use AI in my app?"}],
+        }
+    ],
+    stream=False,
+)
+
+print(response.text)  # typed ChatCompletion response
+print(response.usage)  # token usage when available
+```
+
+### Streaming
+
+```python
+with client.chat.create(
+    model="pawa-v1-ember-20240924",
+    messages=[
+        {"role": "user", "content": [{"type": "text", "text": "Explain RAG in simple terms"}]}
+    ],
+    stream=True,
+) as stream:
+    for delta in stream.text_deltas():
+        print(delta, end="", flush=True)
+
+    # Or collect the full response after streaming
+    completion = stream.collect()
+    print(completion.text)
+```
+
+Async streaming:
+
+```python
+stream = await client.chat.create(..., stream=True)
+text = await stream.collect_text()
+```
+
+### Text-to-Speech
+
+```python
+audio = client.voice.text_to_speech.create(
+    model="pawa-tts-v1-20250704",
+    text="Hello, this is Pawa AI speaking!",
+    voice="liora",
+)
+
+with open("output.mp3", "wb") as f:
+    f.write(audio)
+```
+
+### Embeddings
+
+```python
+response = client.vectors.create(
+    model="pawa-embeddings-v1-20241001",
+    sentences=["Embed this sentence.", "And this one too."],
+    lang="multi",
+)
+
+embeddings = response.embeddings
+```
+
+Pass `raw=True` on any resource method to get the original JSON dict instead of typed models.
+
+### Retries with exponential backoff
+
+```python
+from pawa_ai import PawaAI, RetryConfig
+
+client = PawaAI(
+    retry_config=RetryConfig(
+        max_retries=3,
+        initial_delay=0.5,
+        max_delay=8.0,
+        exponential_base=2.0,
+        jitter=0.1,
+    )
+)
+```
+
+Retries automatically apply to rate limits (429), server errors (500/502/503/504), and connection failures. The SDK respects `Retry-After` response headers when present.
+
+### Async
+
+```python
+import asyncio
+from pawa_ai import AsyncPawaAI
+
+async def main():
+    async with AsyncPawaAI() as client:
+        response = await client.chat.create(
+            model="pawa-v1-ember-20240924",
+            messages=[
+                {"role": "user", "content": [{"type": "text", "text": "Habari yako?"}]}
+            ],
+        )
+        print(response["data"])
+
+asyncio.run(main())
+```
+
+## API coverage
+
+| Resource | Methods |
+|----------|---------|
+| `client.chat` | `create`, `completions` |
+| `client.models` | `list`, `retrieve` |
+| `client.voice.text_to_speech` | `create` |
+| `client.voice.speech_to_text` | `create`, `transcribe` |
+| `client.vectors` | `create`, `embeddings` |
+| `client.documents` | `parse` |
+| `client.agents` | `create`, `update`, `delete`, `list`, `retrieve` |
+| `client.agents.chat` | `create` |
+| `client.storage.knowledge_base` | CRUD, `list_files`, `semantic_retrieval` |
+| `client.transcribe.workspaces` | CRUD, transcription management |
+
+## Error handling
+
+```python
+from pawa_ai import PawaAI, AuthenticationError, RateLimitError, ChatCompletion
+
+client = PawaAI()
+
+try:
+    completion: ChatCompletion = client.chat.create(model="pawa-v1-ember-20240924", messages=[...])
+except AuthenticationError as e:
+    print(f"Auth failed: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited: {e.status_code}")
+```
+
+## Documentation
+
+- [Pawa AI Docs](https://docs.pawa-ai.com)
+- [API Reference](https://docs.pawa-ai.com/api-reference/introduction)
+- [Quickstart Guide](https://docs.pawa-ai.com/get-started/quickstart)
+
+## License
+
+MIT