Khaya SDK

Python SDK for the Khaya AI Khaya API — providing translation, automatic speech recognition (ASR), and text-to-speech (TTS) for African languages.

Installation

pip install khaya

Authentication

Get an API key at https://translation.ghananlp.org and set it as an environment variable:

export KHAYA_API_KEY=your_api_key_here

Quick Start

import os
from khaya import KhayaClient

with KhayaClient(os.environ["KHAYA_API_KEY"]) as khaya:
    # Translate text from English to Twi
    result = khaya.translate("Hello, how are you?", "en-tw")
    print(result.text)

    # Transcribe a Twi audio file
    result = khaya.transcribe("path/to/audio.wav", "tw")
    print(result.text)

    # Synthesize speech in Twi
    result = khaya.synthesize("Me ho yɛ", "twi")
    result.save("output.wav")

Each method returns a typed result object rather than a raw HTTP response: TranslationResult and TranscriptionResult expose .text, and SynthesisResult exposes .audio bytes plus a .save(path) helper.

Async Usage

import asyncio
import os
from khaya import KhayaClient

async def main():
    async with KhayaClient(os.environ["KHAYA_API_KEY"]) as khaya:
        result = await khaya.atranslate("Hello", "en-tw")
        print(result.text)

        result = await khaya.atranscribe("path/to/audio.wav", "tw")
        print(result.text)

        result = await khaya.asynthesize("Me ho yɛ", "twi")
        result.save("output.wav")

asyncio.run(main())

Error Handling

All errors raise exceptions — never return error dicts. Catch the appropriate exception:

from khaya import KhayaClient
from khaya.exceptions import (
    AuthenticationError,
    RateLimitError,
    TranslationError,
    APIError,
)

khaya = KhayaClient(api_key="your-key")

try:
    result = khaya.translate("Hello", "en-tw")
    print(result.text)
except AuthenticationError:
    print("Invalid API key. Check your KHAYA_API_KEY.")
except RateLimitError as e:
    print(f"Rate limit hit: {e.message}")
except TranslationError as e:
    print(f"Translation failed ({e.status_code}): {e.message}")
except APIError as e:
    print(f"API error ({e.status_code}): {e.message}")

Supported Languages

Translation pairs

Language pair format: "<source>-<target>", e.g. "en-tw" or "tw-en". All pairs are bidirectional with English as the pivot language.

ASR languages

TTS languages

Configuration

from khaya import KhayaClient
from khaya.config import Settings

config = Settings(
    api_key="your-key",
    timeout=60,          # seconds (default: 30)
    retry_attempts=5,    # retries on transient failures (default: 3)
)
khaya = KhayaClient(api_key="your-key", config=config)

Development

# Install all dependency groups
uv sync --extra test --extra dev

# Run unit tests (no API key required)
uv run pytest -m "not integration"

# Run with coverage
uv run pytest -m "not integration" --cov=src/khaya --cov-report=term-missing

# Lint and type-check
uv run ruff check src/khaya
uv run mypy src/khaya

# Install pre-commit hooks
uv run pre-commit install

License

MIT