convozen 0.3.1__py3-none-any.whl

convozen/__init__.py

@@ -0,0 +1,45 @@
+__version__ = "0.3.1"
+
+from .client import Client, STT, TTS
+
+from convozen._internal.exceptions import (
+    ConvozenError,
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+from convozen._internal.enums import Language, AudioFormat, VoiceId
+from convozen._internal.types import (
+    TTSResponse,
+    STTResponse,
+    CreditBalance,
+    Credits,
+    AccountInfo,
+    RateLimitInfo,
+    UsageSummary,
+    UsageByDay,
+)
+
+__all__ = [
+    "Client",
+    "STT",
+    "TTS",
+    # Enums
+    "Language",
+    "AudioFormat",
+    "VoiceId",
+    # Types
+    "TTSResponse",
+    "STTResponse",
+    "CreditBalance",
+    "Credits",
+    "AccountInfo",
+    "RateLimitInfo",
+    "UsageSummary",
+    "UsageByDay",
+    # Errors
+    "ConvozenError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIError",
+]

convozen/_internal/account.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import List
+
+from .config import Config
+from .transport.http import HTTPClient
+from .transport.async_http import AsyncHTTPClient
+from .types import AccountInfo, CreditBalance, Credits, RateLimitInfo, UsageSummary, UsageByDay
+
+
+class AccountClient:
+    """
+    HTTP client for account- and usage-related endpoints.
+
+    Expects the API gateway to expose:
+      - GET /v1/account
+      - GET /v1/usage?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._http = HTTPClient(config)
+        self._async_http = AsyncHTTPClient(config)
+
+    # ---- Synchronous API -------------------------------------------------
+
+    def info(self) -> AccountInfo:
+        response = self._http.get("/v1/account")
+        payload = response.json()
+
+        creds = payload.get("credits") or {}
+        tts_creds = creds.get("tts") or {}
+        stt_creds = creds.get("stt") or {}
+        credits = Credits(
+            tts=CreditBalance(balance=tts_creds.get("balance", 0)),
+            stt=CreditBalance(balance=stt_creds.get("balance", 0)),
+        )
+
+        rate = payload.get("rate_limit") or {}
+        rate_limit = RateLimitInfo(
+            requests_per_minute=rate.get("requests_per_minute", 0),
+            requests_per_day=rate.get("requests_per_day", 0),
+        )
+
+        return AccountInfo(
+            account_id=payload.get("account_id", ""),
+            plan=payload.get("plan", ""),
+            credits=credits,
+            rate_limit=rate_limit,
+        )
+
+    def usage(self, start_date: str, end_date: str) -> UsageSummary:
+        response = self._http.get(
+            "/v1/usage",
+            params={"start_date": start_date, "end_date": end_date},
+        )
+        payload = response.json()
+
+        by_day_payload = payload.get("by_day") or []
+        by_day: List[UsageByDay] = [
+            UsageByDay(date=item.get("date", ""), credits=item.get("credits", 0))
+            for item in by_day_payload
+        ]
+
+        return UsageSummary(
+            total_credits_used=payload.get("total_credits_used", 0),
+            by_model=payload.get("by_model", {}),
+            by_day=by_day,
+        )
+
+    # ---- Async API -------------------------------------------------------
+
+    async def ainfo(self) -> AccountInfo:
+        response = await self._async_http.get("/v1/account")
+        payload = response.json()
+
+        creds = payload.get("credits") or {}
+        tts_creds = creds.get("tts") or {}
+        stt_creds = creds.get("stt") or {}
+        credits = Credits(
+            tts=CreditBalance(balance=tts_creds.get("balance", 0)),
+            stt=CreditBalance(balance=stt_creds.get("balance", 0)),
+        )
+
+        rate = payload.get("rate_limit") or {}
+        rate_limit = RateLimitInfo(
+            requests_per_minute=rate.get("requests_per_minute", 0),
+            requests_per_day=rate.get("requests_per_day", 0),
+        )
+
+        return AccountInfo(
+            account_id=payload.get("account_id", ""),
+            plan=payload.get("plan", ""),
+            credits=credits,
+            rate_limit=rate_limit,
+        )
+
+    async def ausage(self, start_date: str, end_date: str) -> UsageSummary:
+        response = await self._async_http.get(
+            "/v1/usage",
+            params={"start_date": start_date, "end_date": end_date},
+        )
+        payload = response.json()
+
+        by_day_payload = payload.get("by_day") or []
+        by_day: List[UsageByDay] = [
+            UsageByDay(date=item.get("date", ""), credits=item.get("credits", 0))
+            for item in by_day_payload
+        ]
+
+        return UsageSummary(
+            total_credits_used=payload.get("total_credits_used", 0),
+            by_model=payload.get("by_model", {}),
+            by_day=by_day,
+        )

convozen/_internal/akshara_stt/__init__.py

@@ -0,0 +1 @@
+from .client import STT

convozen/_internal/akshara_stt/client.py

@@ -0,0 +1,52 @@
+import logging
+
+from ..transport.http import HTTPClient
+from ..transport.async_http import AsyncHTTPClient
+from ..config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class STT:
+
+    def __init__(self, config: Config) -> None:
+        self.http = HTTPClient(config)
+        self.async_http = AsyncHTTPClient(config)
+
+    def transcribe(
+        self,
+        audio: str,
+        model: str = "akshara-v1",
+    ) -> str:
+        logger.debug("STT request: audio=%s model=%s", audio, model)
+
+        with open(audio, "rb") as f:
+            response = self.http.post(
+                "/v1/akshara/transcribe",
+                files={"file": f},
+                data={"model": model},
+            )
+
+        text: str = response.json()["text"]
+        logger.debug("STT response: text_length=%d", len(text))
+        return text
+
+    async def atranscribe(
+        self,
+        audio: str,
+        model: str = "akshara-v1",
+    ) -> str:
+        logger.debug("async STT request: audio=%s model=%s", audio, model)
+
+        with open(audio, "rb") as f:
+            audio_bytes = f.read()
+
+        response = await self.async_http.post(
+            "/v1/akshara/transcribe",
+            files={"file": ("audio", audio_bytes)},
+            data={"model": model},
+        )
+
+        text: str = response.json()["text"]
+        logger.debug("async STT response: text_length=%d", len(text))
+        return text

convozen/_internal/config.py

@@ -0,0 +1,36 @@
+import os
+from dataclasses import dataclass, field
+from urllib.parse import urlparse
+
+
+@dataclass
+class Config:
+    api_key: str = field(default_factory=lambda: os.environ.get("CONVOZEN_API_KEY", ""))
+    base_url: str = field(
+        default_factory=lambda: os.environ.get("CONVOZEN_BASE_URL", "https://voice.convozen.ai/sdk-models/developer-api/api")
+    )
+    timeout: int = 60
+
+    def __post_init__(self) -> None:
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required. Pass it explicitly or set the "
+                "CONVOZEN_API_KEY environment variable."
+            )
+        if not self.base_url:
+            raise ValueError(
+                "base_url is required. Pass it explicitly or set the "
+                "CONVOZEN_BASE_URL environment variable."
+            )
+
+        parsed = urlparse(self.base_url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(
+                f"base_url must start with http:// or https://, got: {self.base_url}"
+            )
+
+        if self.timeout <= 0:
+            raise ValueError(f"timeout must be positive, got: {self.timeout}")
+
+        # Strip trailing slash for consistent URL joining
+        self.base_url = self.base_url.rstrip("/")

convozen/_internal/enums.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Language(str, Enum):
+    """Supported language codes (ISO 639-1)."""
+
+    EN = "en"
+    HI = "hi"
+    TA = "ta"
+    TE = "te"
+    KN = "kn"
+    MR = "mr"
+    BN = "bn"
+    GU = "gu"
+    ML = "ml"
+
+
+class AudioFormat(str, Enum):
+    """Supported audio output formats for TTS."""
+
+    WAV = "wav"
+
+
+class VoiceId(str, Enum):
+    """
+    Available voice IDs for TTS synthesis.
+
+    Backends may support more voices than are listed here; validation
+    functions are designed to accept any non-empty string so we do not
+    block new voices.
+    """
+
+    ROOHI = "roohi"
+    AMAYA = "amaya"
+    KIYANSH = "kiyansh"
+    NEERAJ = "neeraj"
+    MANYA = "manya"
+    NIDHI = "nidhi"
+    IRA = "ira"
+    TRISHA = "trisha"
+    CHARVI = "charvi"

convozen/_internal/exceptions.py

@@ -0,0 +1,14 @@
+class ConvozenError(Exception):
+    pass
+
+
+class AuthenticationError(ConvozenError):
+    pass
+
+
+class RateLimitError(ConvozenError):
+    pass
+
+
+class APIError(ConvozenError):
+    pass

convozen/_internal/ragini_tts/__init__.py

@@ -0,0 +1 @@
+from .client import TTS

convozen/_internal/ragini_tts/client.py

@@ -0,0 +1,123 @@
+import logging
+from typing import AsyncGenerator, Generator, Union
+
+from ..transport.http import HTTPClient
+from ..transport.async_http import AsyncHTTPClient
+from ..config import Config
+from ..utils.validation import (
+    validate_text,
+    validate_language,
+    validate_audio_format,
+    validate_voice,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TTS:
+
+    def __init__(self, config: Config) -> None:
+        self.http = HTTPClient(config)
+        self.async_http = AsyncHTTPClient(config)
+
+    def synthesize(
+        self,
+        text: str,
+        language: str = "en",
+        voice: str = "roohi",
+        model: str = "ragini-v1",
+        format: str = "wav",
+        sample_rate: int = 24000,
+        speed: float = 1.0,
+        stream: bool = False,
+    ) -> Union[bytes, Generator[bytes, None, None]]:
+        text = validate_text(text)
+        language = validate_language(language)
+        format = validate_audio_format(format)
+        voice = validate_voice(voice)
+
+        logger.debug(
+            "TTS request: text_length=%d language=%s voice=%s model=%s "
+            "format=%s sample_rate=%d speed=%.2f stream=%s",
+            len(text), language, voice, model, format, sample_rate, speed, stream,
+        )
+
+        files = {
+            "text": (None, text),
+            "language": (None, language),
+            "speaker": (None, voice),
+            "model": (None, model),
+            "format": (None, format),
+            "sample_rate": (None, str(sample_rate)),
+            "speed": (None, str(speed)),
+            "stream": (None, "true" if stream else "false"),
+        }
+
+        if stream:
+            return self.http.post_stream("/v1/ragini/tts", files=files)
+
+        response = self.http.post("/v1/ragini/tts", files=files)
+
+        logger.debug("TTS response: content_length=%d", len(response.content))
+        return response.content
+
+    async def asynthesize(
+        self,
+        text: str,
+        language: str = "en",
+        voice: str = "roohi",
+        model: str = "ragini-v1",
+        format: str = "wav",
+        sample_rate: int = 24000,
+        speed: float = 1.0,
+        stream: bool = False,
+    ) -> Union[bytes, AsyncGenerator[bytes, None]]:
+        text = validate_text(text)
+        language = validate_language(language)
+        format = validate_audio_format(format)
+        voice = validate_voice(voice)
+
+        logger.debug(
+            "async TTS request: text_length=%d language=%s voice=%s model=%s "
+            "format=%s sample_rate=%d speed=%.2f stream=%s",
+            len(text), language, voice, model, format, sample_rate, speed, stream,
+        )
+
+        files = {
+            "text": (None, text),
+            "language": (None, language),
+            "speaker": (None, voice),
+            "model": (None, model),
+            "format": (None, format),
+            "sample_rate": (None, str(sample_rate)),
+            "speed": (None, str(speed)),
+            "stream": (None, "true" if stream else "false"),
+        }
+
+        if stream:
+            return self.async_http.post_stream("/v1/ragini/tts", files=files)
+
+        response = await self.async_http.post("/v1/ragini/tts", files=files)
+
+        logger.debug("async TTS response: content_length=%d", len(response.content))
+        return response.content
+
+    def generate(
+        self,
+        text: str,
+        language: str = "en",
+        voice: str = "roohi",
+        model: str = "ragini-v1",
+        speed: float = 1.0,
+    ) -> bytes:
+        return self.synthesize(text=text, language=language, voice=voice, model=model, speed=speed)
+
+    async def agenerate(
+        self,
+        text: str,
+        language: str = "en",
+        voice: str = "roohi",
+        model: str = "ragini-v1",
+        speed: float = 1.0,
+    ) -> bytes:
+        return await self.asynthesize(text=text, language=language, voice=voice, model=model, speed=speed)

convozen/_internal/transport/async_http.py

@@ -0,0 +1,165 @@
+import asyncio
+import logging
+from typing import Any, AsyncGenerator, Dict, Optional
+
+try:
+    import httpx
+except ImportError:
+    httpx = None  # type: ignore[assignment]
+
+from ..exceptions import AuthenticationError, RateLimitError, APIError
+from ..config import Config
+
+logger = logging.getLogger(__name__)
+
+# Exceptions that should NOT be retried (non-transient)
+_NON_RETRYABLE = (AuthenticationError, RateLimitError, ValueError, TypeError)
+
+
+def _require_httpx() -> None:
+    if httpx is None:
+        raise ImportError(
+            "httpx is required for async support. "
+            "Install it with: pip install convozen[async]"
+        )
+
+
+async def async_retry_request(func, retries: int = 3, delay: float = 1.0):
+    _require_httpx()
+    for attempt in range(retries):
+        try:
+            return await func()
+        except _NON_RETRYABLE:
+            raise
+        except (httpx.ConnectError, httpx.TimeoutException, OSError) as exc:
+            if attempt == retries - 1:
+                raise
+            wait = delay * (2 ** attempt)
+            logger.warning("Request failed (attempt %d/%d), retrying in %.1fs: %s",
+                           attempt + 1, retries, wait, exc)
+            await asyncio.sleep(wait)
+    raise RuntimeError("Unreachable")
+
+
+class AsyncHTTPClient:
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self._client = None
+
+    async def _get_client(self):
+        _require_httpx()
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                timeout=self.config.timeout,
+                headers={"x-api-key": self.config.api_key},
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "AsyncHTTPClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()
+
+    async def post(
+        self,
+        endpoint: str,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ):
+        return await async_retry_request(
+            lambda: self._request(
+                "POST",
+                endpoint,
+                json=json,
+                files=files,
+                data=data,
+            )
+        )
+
+    async def post_stream(
+        self,
+        endpoint: str,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        chunk_size: int = 4096,
+    ) -> AsyncGenerator[bytes, None]:
+        """POST request that yields response body in chunks (async)."""
+        _require_httpx()
+        url = f"{self.config.base_url}{endpoint}"
+        logger.debug("async stream POST %s", url)
+
+        client = await self._get_client()
+
+        async def _connect():
+            """Establish the stream connection (retryable)."""
+            return await client.send(
+                client.build_request(
+                    "POST", url, json=json, files=files, data=data,
+                ),
+                stream=True,
+            )
+
+        response = await async_retry_request(_connect)
+        try:
+            self._handle_response(response)
+            async for chunk in response.aiter_bytes(chunk_size=chunk_size):
+                yield chunk
+        finally:
+            await response.aclose()
+
+    async def get(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+    ):
+        return await async_retry_request(
+            lambda: self._request("GET", endpoint, params=params)
+        )
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ):
+        url = f"{self.config.base_url}{endpoint}"
+
+        logger.debug("async %s %s", method, url)
+
+        client = await self._get_client()
+        response = await client.request(
+            method,
+            url,
+            json=json,
+            files=files,
+            data=data,
+            params=params,
+        )
+
+        logger.debug("async response: status=%d", response.status_code)
+        self._handle_response(response)
+        return response
+
+    def _handle_response(self, response) -> None:
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API key")
+        if response.status_code == 429:
+            raise RateLimitError("Rate limit exceeded")
+        if not response.is_success:
+            try:
+                body = response.text
+            except Exception:
+                body = f"(status {response.status_code})"
+            raise APIError(f"API error {response.status_code}: {body}")

convozen/_internal/transport/http.py

@@ -0,0 +1,126 @@
+import logging
+from typing import Any, Dict, Generator, Optional
+
+import requests
+
+from ..exceptions import AuthenticationError, RateLimitError, APIError
+from ..config import Config
+from .retry import retry_request
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPClient:
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self._session: Optional[requests.Session] = None
+
+    def _get_session(self) -> requests.Session:
+        if self._session is None:
+            self._session = requests.Session()
+            self._session.headers.update({
+                "x-api-key": self.config.api_key,
+            })
+        return self._session
+
+    def close(self) -> None:
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+
+    def __enter__(self) -> "HTTPClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def post(
+        self,
+        endpoint: str,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        return retry_request(
+            lambda: self._request(
+                "POST",
+                endpoint,
+                json=json,
+                files=files,
+                data=data,
+                stream=stream,
+            )
+        )
+
+    def post_stream(
+        self,
+        endpoint: str,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        chunk_size: int = 4096,
+    ) -> Generator[bytes, None, None]:
+        """POST request that yields response body in chunks."""
+        response = retry_request(
+            lambda: self._request(
+                "POST",
+                endpoint,
+                json=json,
+                files=files,
+                data=data,
+                stream=True,
+            )
+        )
+        for chunk in response.iter_content(chunk_size=chunk_size):
+            if chunk:
+                yield chunk
+
+    def get(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> requests.Response:
+        return retry_request(
+            lambda: self._request("GET", endpoint, params=params)
+        )
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        url = f"{self.config.base_url}{endpoint}"
+
+        logger.debug("%s %s", method, url)
+
+        session = self._get_session()
+
+        response = session.request(
+            method,
+            url,
+            json=json,
+            files=files,
+            data=data,
+            params=params,
+            timeout=self.config.timeout,
+            stream=stream,
+        )
+
+        logger.debug("Response: status=%d", response.status_code)
+        self._handle_response(response)
+        return response
+
+    def _handle_response(self, response: requests.Response) -> None:
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API key")
+        if response.status_code == 429:
+            raise RateLimitError("Rate limit exceeded")
+        if not response.ok:
+            raise APIError(f"API error {response.status_code}: {response.text}")

convozen/_internal/transport/retry.py

@@ -0,0 +1,30 @@
+import logging
+import time
+from typing import Callable, TypeVar
+
+import requests
+
+from ..exceptions import AuthenticationError, RateLimitError
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# Exceptions that should NOT be retried (non-transient)
+_NON_RETRYABLE = (AuthenticationError, RateLimitError, ValueError, TypeError)
+
+
+def retry_request(func: Callable[[], T], retries: int = 3, delay: float = 1.0) -> T:
+    for attempt in range(retries):
+        try:
+            return func()
+        except _NON_RETRYABLE:
+            raise
+        except (requests.ConnectionError, requests.Timeout, OSError) as exc:
+            if attempt == retries - 1:
+                raise
+            wait = delay * (2 ** attempt)
+            logger.warning("Request failed (attempt %d/%d), retrying in %.1fs: %s",
+                           attempt + 1, retries, wait, exc)
+            time.sleep(wait)
+    raise RuntimeError("Unreachable")

convozen/_internal/types.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+@dataclass
+class TTSResponse:
+    audio: bytes
+    duration: float
+
+
+@dataclass
+class STTResponse:
+    text: str
+    language: str
+
+
+@dataclass
+class CreditBalance:
+    balance: int
+
+
+@dataclass
+class Credits:
+    tts: CreditBalance
+    stt: CreditBalance
+
+
+@dataclass
+class RateLimitInfo:
+    requests_per_minute: int
+    requests_per_day: int
+
+
+@dataclass
+class AccountInfo:
+    account_id: str
+    plan: str
+    credits: Credits
+    rate_limit: RateLimitInfo
+
+
+@dataclass
+class UsageByDay:
+    date: str
+    credits: int
+
+
+@dataclass
+class UsageSummary:
+    total_credits_used: int
+    by_model: Dict[str, int]
+    by_day: List[UsageByDay]

convozen/_internal/utils/audio.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+from typing import Union
+
+
+def save_wav(audio_bytes: bytes, path: Union[str, Path]) -> None:
+    with open(path, "wb") as f:
+        f.write(audio_bytes)

convozen/_internal/utils/validation.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Union
+
+from ..enums import Language, AudioFormat, VoiceId
+
+
+def validate_text(text: str) -> str:
+    if not text:
+        raise ValueError("Text cannot be empty")
+    return text
+
+
+def validate_language(language: Union[str, Language]) -> str:
+    """
+    Ensure the language is one of the supported ISO 639-1 codes.
+    """
+    if isinstance(language, Language):
+        return language.value
+
+    lang = language.lower()
+    if lang not in {l.value for l in Language}:
+        raise ValueError(f"Unsupported language code: {language}")
+    return lang
+
+
+def validate_audio_format(fmt: Union[str, AudioFormat]) -> str:
+    """
+    Ensure the audio format is supported for TTS outputs.
+    """
+    if isinstance(fmt, AudioFormat):
+        return fmt.value
+
+    norm = fmt.lower()
+    if norm not in {AudioFormat.WAV.value}:
+        raise ValueError(f"Unsupported audio format: {fmt}")
+    return norm
+
+
+def validate_voice(voice: Union[str, VoiceId]) -> str:
+    """
+    Basic validation for voice identifiers.
+
+    For now we accept any non-empty string so that new voices can be
+    introduced server-side without requiring an SDK update, but keep a
+    typed enum for common voices.
+    """
+    if isinstance(voice, VoiceId):
+        value = voice.value
+    else:
+        value = str(voice).strip()
+
+    if not value:
+        raise ValueError("Voice identifier cannot be empty")
+
+    return value

convozen/client.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import Optional, Any
+
+from convozen._internal.config import Config
+from convozen._internal.akshara_stt.client import STT as _STTImpl
+from convozen._internal.ragini_tts.client import TTS as _TTSImpl
+from convozen._internal.account import AccountClient
+
+
+class Client:
+    """
+    Public entrypoint for the ConvoZen SDK.
+
+    Usage::
+
+        import convozen
+
+        client = convozen.Client(api_key="your-api-key-here")
+        text = client.stt.transcribe("audio.wav")
+        audio = client.tts.synthesize("Hello world")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[int] = None,
+    ) -> None:
+        config_kwargs = {}
+        if api_key is not None:
+            config_kwargs["api_key"] = api_key
+        if base_url is not None:
+            config_kwargs["base_url"] = base_url
+        if timeout is not None:
+            config_kwargs["timeout"] = timeout
+
+        config = Config(**config_kwargs)
+
+        self.stt = _STTImpl(config)
+        self.tts = _TTSImpl(config)
+        self.account = AccountClient(config)
+
+
+class STT:
+    """
+    Convenience wrapper::
+
+        from convozen import STT
+        stt = STT(api_key="...")
+        stt.transcribe("audio.wav")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[int] = None,
+    ) -> None:
+        config_kwargs = {}
+        if api_key is not None:
+            config_kwargs["api_key"] = api_key
+        if base_url is not None:
+            config_kwargs["base_url"] = base_url
+        if timeout is not None:
+            config_kwargs["timeout"] = timeout
+
+        config = Config(**config_kwargs)
+        self._client = _STTImpl(config)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class TTS:
+    """
+    Convenience wrapper::
+
+        from convozen import TTS
+        tts = TTS(api_key="...")
+        tts.synthesize("Hello world")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[int] = None,
+    ) -> None:
+        config_kwargs = {}
+        if api_key is not None:
+            config_kwargs["api_key"] = api_key
+        if base_url is not None:
+            config_kwargs["base_url"] = base_url
+        if timeout is not None:
+            config_kwargs["timeout"] = timeout
+
+        config = Config(**config_kwargs)
+        self._client = _TTSImpl(config)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

convozen-0.3.1.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: convozen
+Version: 0.3.1
+Summary: Python SDK for ConvoZen TTS and STT services
+Author: Convozen
+License-Expression: MIT
+Keywords: tts,stt,speech,voice,convozen
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0,>=2.28.0
+Provides-Extra: async
+Requires-Dist: httpx<1.0,>=0.24.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: anyio[trio]; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Requires-Dist: httpx<1.0,>=0.24.0; extra == "dev"
+Dynamic: license-file
+
+# ConvoZen Voice SDK
+
+Text-to-Speech (TTS) and Speech-to-Text (STT) for Python.
+
+> One API key for both TTS and STT.
+
+## Install
+
+```bash
+pip install convozen
+```
+
+Requires Python 3.9+
+
+---
+
+## TTS — Convert Text to Speech
+
+Copy and run:
+
+```python
+import convozen
+
+client = convozen.Client(api_key="your-api-key")
+
+audio = client.tts.synthesize("नमस्ते… मुझे आपके सर्विस के बारे में थोड़ी जानकारी चाहिए।", language="hi")
+
+with open("output.wav", "wb") as f:
+    f.write(audio)
+```
+
+With options:
+
+```python
+import convozen
+
+client = convozen.Client(api_key="your-api-key")
+
+audio = client.tts.synthesize(
+    text="Welcome to Playground.",
+    language="en",          # default: "en"
+    voice="roohi",          # default: "roohi"
+    model="ragini-v1",      # default: "ragini-v1"
+    speed=1.2,              # default: 1.0
+)
+
+with open("output.wav", "wb") as f:
+    f.write(audio)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text` | `str` | *required* | Text to convert to speech |
+| `language` | `str` | `"en"` | Language code (see supported languages below) |
+| `voice` | `str` | `"roohi"` | Voice ID for synthesis (see available voices below) |
+| `model` | `str` | `"ragini-v1"` | TTS model to use. Currently only `ragini-v1` is available |
+| `speed` | `float` | `1.0` | Speech speed. `0.5` = half speed, `2.0` = double speed |
+| `stream` | `bool` | `False` | If `True`, returns audio chunks as they are generated |
+| `format` | `str` | `"wav"` | Audio output format. Currently only `wav` is supported |
+
+### Streaming
+
+```python
+import convozen
+
+client = convozen.Client(api_key="your-api-key")
+
+for chunk in client.tts.synthesize("Long text here...", language="en", stream=True):
+    audio_player.write(chunk)
+```
+
+### Available Voices
+
+| Voice | ID | Default |
+|-------|----|---------|
+| Roohi | `roohi` | Yes |
+| Amaya | `amaya` | |
+| Kiyansh | `kiyansh` | |
+| Neeraj | `neeraj` | |
+| Manya | `manya` | |
+| Nidhi | `nidhi` | |
+| Ira | `ira` | |
+| Trisha | `trisha` | |
+| Charvi | `charvi` | |
+
+```python
+audio = client.tts.synthesize("Hello", language="en", voice="roohi")
+```
+
+---
+
+## STT — Convert Speech to Text
+
+Copy and run:
+
+```python
+import convozen
+
+client = convozen.Client(api_key="your-api-key")
+
+text = client.stt.transcribe("recording.wav")
+print(text)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `audio` | `str` | *required* | Path to the audio file (WAV format) |
+| `model` | `str` | `"akshara-v1"` | STT model to use. Currently only `akshara-v1` is available |
+
+---
+
+## Supported Languages
+
+| Code | Language | TTS | STT |
+|------|----------|:---:|:---:|
+| `en` | English | Yes | Yes |
+| `hi` | Hindi | Yes | Yes |
+| `ta` | Tamil | Yes | Yes |
+| `te` | Telugu | Yes | Yes |
+| `kn` | Kannada | Yes | Yes |
+| `mr` | Marathi | — | Yes |
+| `bn` | Bengali | — | Yes |
+| `gu` | Gujarati | — | Yes |
+| `ml` | Malayalam | — | Yes |
+
+---
+
+## Check Credits
+
+```python
+import convozen
+
+client = convozen.Client(api_key="your-api-key")
+info = client.account.info()
+print(info.credits.tts.balance)
+print(info.credits.stt.balance)
+```
+
+---
+
+## Error Handling
+
+```python
+import convozen
+from convozen import AuthenticationError, RateLimitError, APIError
+
+client = convozen.Client(api_key="your-api-key")
+
+try:
+    audio = client.tts.synthesize("Hello")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError:
+    print("Too many requests")
+except APIError as e:
+    print(f"Server error: {e}")
+```
+
+---
+
+## Standalone Clients
+
+```python
+from convozen import TTS, STT
+
+tts = TTS(api_key="your-api-key")
+audio = tts.synthesize("Hello", language="hi")
+
+stt = STT(api_key="your-api-key")
+text = stt.transcribe("audio.wav")
+```

convozen-0.3.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+convozen/__init__.py,sha256=I6VwAF-RadaZMB5jnr1JL1x2szhLO_IFcXUdkDgvGlM,806
+convozen/client.py,sha256=ahxK73-cM5_lZDr5k9W0myhZ4QGzm-A92cf3veUqUzM,2698
+convozen/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+convozen/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+convozen/_internal/account.py,sha256=D3jBTStJPaAwgULKvBRrUyY8X53u8OO6d6PXgOyOO4c,3858
+convozen/_internal/config.py,sha256=RDDdzShkUft7alzylCT1a2XFfhb9WqRZ_Iq6H9Dx6pU,1265
+convozen/_internal/enums.py,sha256=TcroRu7-J04fdsYU7c_A-ak6Iuwpe0JkGZUuQWxiAb8,799
+convozen/_internal/exceptions.py,sha256=wTpqBoM5tNrgDnKUkbqFLEKSUT0Z0Z9CWNoGtYr2t1g,184
+convozen/_internal/types.py,sha256=AlvqktxTMKhjk9qeqVOYdxaf_YpvSENUxvMD43mZccs,709
+convozen/_internal/akshara_stt/__init__.py,sha256=aNN4N9nAZnlS_5haDEWWUde1Zzqmb7arMg1cmGIDm6k,24
+convozen/_internal/akshara_stt/client.py,sha256=JLTi1A8kyzVjyny_W37PLx5EEywJCIIEvfX6IGUg7sQ,1410
+convozen/_internal/ragini_tts/__init__.py,sha256=DU2AnUeJpZtvkAAX2JJq2gioYsxehjQ5OiqRgEpGYMI,24
+convozen/_internal/ragini_tts/client.py,sha256=OAjBFcTi-Apz2z8hzfR_M1J-dPOgifQ1ckGmogU3MYY,3892
+convozen/_internal/transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+convozen/_internal/transport/async_http.py,sha256=fF9iVF8p-u044frOAYTN2kP3K5ARE7X3iYvdB4jrDpA,5076
+convozen/_internal/transport/http.py,sha256=MoLN1QX7DUWZ47nRUO5Zeza5rQWCrgsvLWhV7ukOqxY,3627
+convozen/_internal/transport/retry.py,sha256=LFbU0j3vGYd90gHjR9VgUOKRAfUgTzRh4-u-6njQj8Y,935
+convozen/_internal/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+convozen/_internal/utils/audio.py,sha256=KL_mrERWyZqI94iKoBbs9p7-j7nXG8jRd0fXzzGCWBc,179
+convozen/_internal/utils/validation.py,sha256=NAjj9sX_3qHiqCLolv2CzhhFAvkikrQYLRQbkJ6xd7o,1453
+convozen-0.3.1.dist-info/licenses/LICENSE,sha256=XE2zp0Dsy70q77MwihQBxfquD5zTonLOer5wyhyPzN4,1065
+convozen-0.3.1.dist-info/METADATA,sha256=pDcnhwSY1GxLMRN73--4WNZlRlncHozAFA1ZxFMT2YA,5054
+convozen-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+convozen-0.3.1.dist-info/top_level.txt,sha256=CPeafodt_r-UaGseHmK4ROv0yr9V8Jk7I7WZ5Cg544s,9
+convozen-0.3.1.dist-info/RECORD,,

convozen-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

convozen-0.3.1.dist-info/licenses/LICENSE

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

convozen-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+convozen