Metadata-Version: 2.4
Name: makimoto-kawa
Version: 0.1.1
Summary: Official Python SDK for the Makimoto transcription API
Author-email: Xavier Choa <xavier.choa@makimoto.ai>
Maintainer-email: Makimoto <contact@makimoto.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/makimoto-ai/makimoto-python
Project-URL: Repository, https://github.com/makimoto-ai/makimoto-python
Project-URL: Issues, https://github.com/makimoto-ai/makimoto-python/issues
Project-URL: Changelog, https://github.com/makimoto-ai/makimoto-python/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx2<3,>=2.7.0
Requires-Dist: pydantic<3,>=1.10.13
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-httpx2>=1.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Requires-Dist: gitlint>=0.19; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# makimoto-kawa

[![CI](https://github.com/makimoto-ai/makimoto-python/actions/workflows/ci.yml/badge.svg)](https://github.com/makimoto-ai/makimoto-python/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/makimoto-kawa)](https://pypi.org/project/makimoto-kawa/)
[![Python versions](https://img.shields.io/pypi/pyversions/makimoto-kawa)](https://pypi.org/project/makimoto-kawa/)
[![License](https://img.shields.io/github/license/makimoto-ai/makimoto-python?cachebust=1)](https://github.com/makimoto-ai/makimoto-python/blob/main/LICENSE)

Official Python SDK for [Kawa](https://github.com/makimoto-ai/kawa)'s transcription API. `makimoto` is the shared namespace this SDK lives under, `kawa` is the specific product it talks to, more Makimoto products may get their own subpackage here later.

This is the maintained, typed client, with `pydantic` response models, structured exceptions, and a tested, versioned release process, built on top of the same API as the reference client in the main `kawa` repo. For the interactive [playground](https://github.com/makimoto-ai/kawa/tree/main/demo), full [API docs](https://github.com/makimoto-ai/kawa/blob/main/docs/api-authentication-quickstart.md), and the [OpenAPI spec](https://github.com/makimoto-ai/kawa/blob/main/docs/openapi.json), see the main `kawa` repo. Prefer a zero-dependency, copy-paste client instead of a pip package? See [`kawa_client.py`](https://github.com/makimoto-ai/kawa/blob/main/demo/kawa_client.py) there.

## Install

Requires Python 3.10+.

```bash
pip install makimoto-kawa
```

## Authentication

Get a token from the Makimoto dashboard: <https://www.makimoto.ai/login>.

For now, this is a short-lived JWT, not a persistent API key, it expires, so copy a fresh one from the dashboard if requests start failing with `401`. This will change to a static API key in the near future; when it does, the same `token`/`MAKIMOTO_API_TOKEN` mechanism below will keep working, only what you paste in changes.

```python
client = kawa.KawaClient(token="<dashboard-token>")
```

or set it once as an environment variable and omit the argument entirely:

```bash
export MAKIMOTO_API_TOKEN="<dashboard-token>"
```

An explicit `token` argument always wins over the environment variable if both are set.

## Usage

```python
from makimoto import kawa

client = kawa.KawaClient(token="<dashboard-token>")   # or set MAKIMOTO_API_TOKEN instead

job = client.transcribe("call.mp3", language="en")

if job.status == "succeeded":
    print(job.result.full_text)
else:
    print(job.error)
```

See [`examples/quickstart.py`](https://github.com/makimoto-ai/makimoto-python/blob/main/examples/quickstart.py) for a complete, runnable script, it ships with a small sample audio file, so `python examples/quickstart.py` works out of the box once `MAKIMOTO_API_TOKEN` is set.

`transcribe()` submits the recording and polls until it's done in one call, raising `TimeoutError` if it never finishes. For manual control, e.g. streaming live status updates to a UI, the lower-level primitives are still there:

```python
job = client.create_transcription("call.mp3", language="en")

for update in client.poll(job.job_id):
    print(update.status)
```

Check your account's transcription quota:

```python
usage = client.usage()
print(f"{usage.used_minutes}/{usage.limit_minutes} minutes used")
```

Release the client's connections when you're done with it, or use it as a context manager:

```python
with kawa.KawaClient(token="<dashboard-token>") as client:
    ...
```

## Errors

Every call raises `kawa.KawaError` on an API-level failure (bad status code, or a response that doesn't match the expected shape), and `kawa.TimeoutError`-compatible `TimeoutError` from `transcribe()` if a job never finishes in time. A failed transcription job (`status == "failed"`) is not an exception, it's a normal result, check `.status`/`.error` as shown above.

```python
try:
    job = client.transcribe("call.mp3")
except kawa.KawaError as exc:
    print(exc.status_code, exc.body)
```

## Logging

Quiet by default. To see what the SDK is doing (credential source, a poll that gave up), or the raw HTTP traffic underneath it:

```python
import logging
logging.basicConfig()  # attaches a handler so the lines below actually print somewhere
logging.getLogger("makimoto.kawa.client").setLevel(logging.DEBUG)  # this SDK's own events
logging.getLogger("httpx2").setLevel(logging.DEBUG)                 # every request/response
```

## Development

See [`CONTRIBUTING.md`](https://github.com/makimoto-ai/makimoto-python/blob/main/CONTRIBUTING.md).

## Licence

[MIT](https://github.com/makimoto-ai/makimoto-python/blob/main/LICENSE)
