hyperneuronai 0.1.0__py3-none-any.whl

hyperneuronai/__init__.py

@@ -0,0 +1,91 @@
+"""
+hyperneuronai — Official Python SDK for HyperNeuron AI services.
+
+Quick start (sync)::
+
+    import hyperneuronai
+
+    client = hyperneuronai.HyperNeuron(api_key="hn_key_xxxx")
+
+    # TTS — save to file
+    audio = client.tts.generate("Hello, world!", voice="sanjana")
+    with open("hello.wav", "wb") as f:
+        f.write(audio)
+
+    # TTS — stream in real-time
+    for chunk in client.tts.stream("Hello, world!", voice="sanjana"):
+        your_speaker.write(chunk)
+
+    # Outbound call
+    call = client.telephony.call(
+        to="+919876543210",
+        voice="sanjana",
+        greeting="Hi! I'm calling to help you today.",
+    )
+    print(call.call_uuid)
+
+Quick start (async)::
+
+    import asyncio
+    import hyperneuronai
+
+    async def main():
+        client = hyperneuronai.AsyncHyperNeuron(api_key="hn_key_xxxx")
+
+        audio = await client.tts.generate("Hello!", voice="sanjana")
+
+        async for chunk in client.tts.stream("Hello!"):
+            await speaker.write(chunk)
+
+        call = await client.telephony.call(to="+919876543210")
+
+    asyncio.run(main())
+"""
+
+from hyperneuronai._hyperneuron import HyperNeuron, AsyncHyperNeuron
+from hyperneuronai.exceptions import (
+    HyperNeuronError,
+    APIError,
+    AuthenticationError,
+    PermissionError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    APIConnectionError,
+)
+from hyperneuronai.types import (
+    TTSRequest,
+    TTSResponse,
+    AudioFormat,
+    Voice,
+    CallRequest,
+    CallResponse,
+    CallStatus,
+    CallState,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "HyperNeuron",
+    "AsyncHyperNeuron",
+    # Exceptions
+    "HyperNeuronError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "APIConnectionError",
+    # Types
+    "TTSRequest",
+    "TTSResponse",
+    "AudioFormat",
+    "Voice",
+    "CallRequest",
+    "CallResponse",
+    "CallStatus",
+    "CallState",
+]

hyperneuronai/_client.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from typing import Any, Iterator, AsyncIterator, Optional
+import warnings
+
+import httpx
+
+from hyperneuronai.exceptions import APIConnectionError, _raise_for_status
+
+_DEFAULT_TIMEOUT = httpx.Timeout(connect=10.0, read=120.0, write=30.0, pool=10.0)
+_DEFAULT_BASE_URL = "https://api.hyperneuron.ai"
+_MAX_RESPONSE_BYTES = 64 * 1024 * 1024  # 64 MB hard cap on non-streaming responses
+
+
+def _validate_base_url(url: str) -> None:
+    if url.startswith("http://"):
+        warnings.warn(
+            "base_url uses plain HTTP — your API key will be sent unencrypted. "
+            "Use HTTPS in production.",
+            stacklevel=3,
+        )
+
+
+def _auth_headers(api_key: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {api_key}"}
+
+
+# ── Sync ──────────────────────────────────────────────────────────────────────
+
+
+class SyncHTTPClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: Optional[httpx.Timeout] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        _validate_base_url(base_url)
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = http_client or httpx.Client(
+            timeout=timeout or _DEFAULT_TIMEOUT,
+            headers={"User-Agent": "hyperneuronai-python/0.1.0"},
+        )
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    def _headers(self, extra: Optional[dict] = None) -> dict[str, str]:
+        h = _auth_headers(self._api_key)
+        if extra:
+            h.update(extra)
+        return h
+
+    def post(self, path: str, *, json_body: Any = None) -> dict:
+        try:
+            r = self._client.post(
+                self._url(path),
+                json=json_body,
+                headers=self._headers({"Content-Type": "application/json"}),
+            )
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+        self._check(r)
+        return r.json()
+
+    def get(self, path: str) -> dict:
+        try:
+            r = self._client.get(self._url(path), headers=self._headers())
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+        self._check(r)
+        return r.json()
+
+    def delete(self, path: str) -> dict:
+        try:
+            r = self._client.delete(self._url(path), headers=self._headers())
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+        self._check(r)
+        return r.json()
+
+    def stream_bytes(self, path: str, *, json_body: Any = None) -> Iterator[bytes]:
+        try:
+            with self._client.stream(
+                "POST",
+                self._url(path),
+                json=json_body,
+                headers=self._headers({"Content-Type": "application/json"}),
+            ) as r:
+                self._check(r)
+                yield from r.iter_bytes(chunk_size=4096)
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+
+    def _check(self, r: httpx.Response) -> None:
+        if r.status_code >= 400:
+            try:
+                body = r.json()
+            except Exception:
+                body = {}
+            # Truncate raw text to avoid leaking large server error pages.
+            _raise_for_status(r.status_code, body, r.text[:300])
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "SyncHTTPClient":
+        return self
+
+    def __repr__(self) -> str:
+        return f"SyncHTTPClient(base_url={self._base_url!r}, api_key='***')"
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+# ── Async ─────────────────────────────────────────────────────────────────────
+
+
+class AsyncHTTPClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: Optional[httpx.Timeout] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        _validate_base_url(base_url)
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = http_client or httpx.AsyncClient(
+            timeout=timeout or _DEFAULT_TIMEOUT,
+            headers={"User-Agent": "hyperneuronai-python/0.1.0"},
+        )
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    def _headers(self, extra: Optional[dict] = None) -> dict[str, str]:
+        h = _auth_headers(self._api_key)
+        if extra:
+            h.update(extra)
+        return h
+
+    async def post(self, path: str, *, json_body: Any = None) -> dict:
+        try:
+            r = await self._client.post(
+                self._url(path),
+                json=json_body,
+                headers=self._headers({"Content-Type": "application/json"}),
+            )
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+        self._check(r)
+        return r.json()
+
+    async def get(self, path: str) -> dict:
+        try:
+            r = await self._client.get(self._url(path), headers=self._headers())
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+        self._check(r)
+        return r.json()
+
+    async def delete(self, path: str) -> dict:
+        try:
+            r = await self._client.delete(self._url(path), headers=self._headers())
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+        self._check(r)
+        return r.json()
+
+    async def stream_bytes(self, path: str, *, json_body: Any = None) -> AsyncIterator[bytes]:
+        try:
+            async with self._client.stream(
+                "POST",
+                self._url(path),
+                json=json_body,
+                headers=self._headers({"Content-Type": "application/json"}),
+            ) as r:
+                self._check(r)
+                async for chunk in r.aiter_bytes(chunk_size=4096):
+                    yield chunk
+        except httpx.RequestError as exc:
+            raise APIConnectionError(str(exc)) from exc
+
+    def _check(self, r: httpx.Response) -> None:
+        if r.status_code >= 400:
+            try:
+                body = r.json()
+            except Exception:
+                body = {}
+            _raise_for_status(r.status_code, body, r.text[:300])
+
+    def __repr__(self) -> str:
+        return f"AsyncHTTPClient(base_url={self._base_url!r}, api_key='***')"
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHTTPClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

hyperneuronai/_hyperneuron.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from hyperneuronai._client import (
+    SyncHTTPClient,
+    AsyncHTTPClient,
+    _DEFAULT_BASE_URL,
+    _DEFAULT_TIMEOUT,
+)
+from hyperneuronai.resources.tts import TTS, AsyncTTS
+from hyperneuronai.resources.telephony import Telephony, AsyncTelephony
+
+
+class HyperNeuron:
+    """
+    Synchronous HyperNeuron AI client.
+
+    Parameters
+    ----------
+    api_key:
+        Your HyperNeuron API key (starts with ``hn_key_``).
+    base_url:
+        Server base URL. Defaults to ``https://api.hyperneuron.ai``.
+        Override to point at a self-hosted instance.
+    timeout:
+        Custom ``httpx.Timeout``. Defaults to 10 s connect / 120 s read.
+    http_client:
+        Bring your own ``httpx.Client`` (useful for proxies, custom SSL, etc.).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: Optional[httpx.Timeout] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty.")
+        self._http = SyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.tts = TTS(self._http)
+        self.telephony = Telephony(self._http)
+
+    def __repr__(self) -> str:
+        return f"HyperNeuron(base_url={self._http._base_url!r}, api_key='***')"
+
+    def health(self) -> dict:
+        """Check server health and model loading status."""
+        return self._http.get("/health")
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "HyperNeuron":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+
+class AsyncHyperNeuron:
+    """
+    Async HyperNeuron AI client.
+
+    Parameters
+    ----------
+    api_key:
+        Your HyperNeuron API key (starts with ``hn_key_``).
+    base_url:
+        Server base URL. Defaults to ``https://api.hyperneuron.ai``.
+    timeout:
+        Custom ``httpx.Timeout``.
+    http_client:
+        Bring your own ``httpx.AsyncClient``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: Optional[httpx.Timeout] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty.")
+        self._http = AsyncHTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.tts = AsyncTTS(self._http)
+        self.telephony = AsyncTelephony(self._http)
+
+    def __repr__(self) -> str:
+        return f"AsyncHyperNeuron(base_url={self._http._base_url!r}, api_key='***')"
+
+    async def health(self) -> dict:
+        """Check server health and model loading status."""
+        return await self._http.get("/health")
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncHyperNeuron":
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.aclose()

hyperneuronai/exceptions.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class HyperNeuronError(Exception):
+    """Base exception for all HyperNeuron SDK errors."""
+
+
+class APIError(HyperNeuronError):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, message: str, status_code: int, body: Optional[dict] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body or {}
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status_code={self.status_code}, message={str(self)!r})"
+
+
+class AuthenticationError(APIError):
+    """401 — invalid or missing API key."""
+
+
+class PermissionError(APIError):
+    """403 — API key lacks permission for this resource."""
+
+
+class NotFoundError(APIError):
+    """404 — resource not found."""
+
+
+class RateLimitError(APIError):
+    """429 — rate limit exceeded."""
+
+
+class ServiceUnavailableError(APIError):
+    """503 — service temporarily unavailable (models loading, etc.)."""
+
+
+class APIConnectionError(HyperNeuronError):
+    """Network-level error (timeout, DNS failure, etc.)."""
+
+
+def _raise_for_status(status_code: int, body: dict, raw: str) -> None:
+    message = body.get("detail") or body.get("message") or raw or f"HTTP {status_code}"
+    cls_map = {
+        401: AuthenticationError,
+        403: PermissionError,
+        404: NotFoundError,
+        429: RateLimitError,
+        503: ServiceUnavailableError,
+    }
+    cls = cls_map.get(status_code, APIError)
+    raise cls(message, status_code, body)

hyperneuronai/resources/__init__.py

@@ -0,0 +1,4 @@
+from hyperneuronai.resources.tts import TTS, AsyncTTS
+from hyperneuronai.resources.telephony import Telephony, AsyncTelephony
+
+__all__ = ["TTS", "AsyncTTS", "Telephony", "AsyncTelephony"]

hyperneuronai/resources/telephony.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from hyperneuronai._client import SyncHTTPClient, AsyncHTTPClient
+from hyperneuronai.types.telephony import OutboundCallRequest, CallResponse, CallStatus
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+
+_AGENT_CALL_NOT_IMPLEMENTED = (
+    "agent_call() is not yet available in this SDK version. "
+    "It will be enabled in an upcoming release."
+)
+
+
+def _validate_call_uuid(call_uuid: str) -> None:
+    if not _UUID_RE.match(call_uuid):
+        raise ValueError(f"Invalid call_uuid: {call_uuid!r}. Must be a UUID string.")
+
+
+def _validate_pagination(limit: int, offset: int) -> None:
+    if not (1 <= limit <= 100):
+        raise ValueError(f"limit must be between 1 and 100, got {limit}.")
+    if offset < 0:
+        raise ValueError(f"offset must be >= 0, got {offset}.")
+
+
+# ── Sync ──────────────────────────────────────────────────────────────────────
+
+
+class Telephony:
+    """
+    Synchronous telephony resource.
+
+    Enabled
+    -------
+    ``outbound()`` — one-way call: synthesizes ``text`` via TTS and delivers
+    the audio to the recipient. No interaction from the called party.
+
+    Coming soon
+    -----------
+    ``agent_call()`` — two-way AI voice conversation. Currently raises
+    ``NotImplementedError``.
+
+    Usage::
+
+        call = client.telephony.outbound(
+            to="+919876543210",
+            text="Hi! Your order has been shipped and will arrive tomorrow.",
+            voice="sanjana",
+        )
+        print(call.call_uuid, call.state)
+
+        status = client.telephony.status(call.call_uuid)
+        client.telephony.end(call.call_uuid)
+    """
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def outbound(
+        self,
+        to: str,
+        text: str,
+        *,
+        voice: str = "sanjana",
+        language: str = "en",
+        metadata: Optional[dict] = None,
+    ) -> CallResponse:
+        """
+        Initiate a one-way outbound call.
+
+        The TTS model synthesizes ``text`` and plays the audio to the
+        recipient. The called party cannot speak back.
+
+        Parameters
+        ----------
+        to:
+            E.164 phone number, e.g. ``"+919876543210"``.
+        text:
+            Message to synthesize and deliver (1–4096 characters).
+        voice:
+            TTS voice name, e.g. ``"sanjana"``.
+        language:
+            BCP-47 language code for synthesis, e.g. ``"en"``, ``"hi"``.
+        metadata:
+            Arbitrary key/value pairs for your own tracking.
+        """
+        req = OutboundCallRequest(
+            to=to,
+            text=text,
+            voice=voice,
+            language=language,
+            metadata=metadata or {},
+        )
+        data = self._http.post("/telephony/outbound", json_body=req.model_dump())
+        return CallResponse(**data)
+
+    def agent_call(self) -> None:
+        """Two-way AI voice call — not yet implemented."""
+        raise NotImplementedError(_AGENT_CALL_NOT_IMPLEMENTED)
+
+    def status(self, call_uuid: str) -> CallStatus:
+        """Fetch the current status of a call."""
+        _validate_call_uuid(call_uuid)
+        data = self._http.get(f"/telephony/call/{call_uuid}")
+        return CallStatus(**data)
+
+    def end(self, call_uuid: str) -> dict:
+        """Terminate an active call immediately."""
+        _validate_call_uuid(call_uuid)
+        return self._http.delete(f"/telephony/call/{call_uuid}")
+
+    def list_calls(self, limit: int = 20, offset: int = 0) -> list[CallStatus]:
+        """List recent calls for this API key."""
+        _validate_pagination(limit, offset)
+        data = self._http.get(f"/telephony/calls?limit={limit}&offset={offset}")
+        calls = data if isinstance(data, list) else data.get("calls", [])
+        return [CallStatus(**c) for c in calls]
+
+
+# ── Async ─────────────────────────────────────────────────────────────────────
+
+
+class AsyncTelephony:
+    """
+    Async telephony resource.
+
+    Usage::
+
+        call = await client.telephony.outbound(
+            to="+919876543210",
+            text="Hi! Your order has been shipped and will arrive tomorrow.",
+            voice="sanjana",
+        )
+
+        status = await client.telephony.status(call.call_uuid)
+        await client.telephony.end(call.call_uuid)
+    """
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def outbound(
+        self,
+        to: str,
+        text: str,
+        *,
+        voice: str = "sanjana",
+        language: str = "en",
+        metadata: Optional[dict] = None,
+    ) -> CallResponse:
+        """Initiate a one-way outbound call (async)."""
+        req = OutboundCallRequest(
+            to=to,
+            text=text,
+            voice=voice,
+            language=language,
+            metadata=metadata or {},
+        )
+        data = await self._http.post("/telephony/outbound", json_body=req.model_dump())
+        return CallResponse(**data)
+
+    async def agent_call(self) -> None:
+        """Two-way AI voice call — not yet implemented."""
+        raise NotImplementedError(_AGENT_CALL_NOT_IMPLEMENTED)
+
+    async def status(self, call_uuid: str) -> CallStatus:
+        """Fetch the current status of a call."""
+        _validate_call_uuid(call_uuid)
+        data = await self._http.get(f"/telephony/call/{call_uuid}")
+        return CallStatus(**data)
+
+    async def end(self, call_uuid: str) -> dict:
+        """Terminate an active call immediately."""
+        _validate_call_uuid(call_uuid)
+        return await self._http.delete(f"/telephony/call/{call_uuid}")
+
+    async def list_calls(self, limit: int = 20, offset: int = 0) -> list[CallStatus]:
+        """List recent calls for this API key."""
+        _validate_pagination(limit, offset)
+        data = await self._http.get(f"/telephony/calls?limit={limit}&offset={offset}")
+        calls = data if isinstance(data, list) else data.get("calls", [])
+        return [CallStatus(**c) for c in calls]

hyperneuronai/resources/tts.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import io
+import struct
+import wave
+from typing import Iterator, AsyncIterator, Optional
+
+from hyperneuronai._client import SyncHTTPClient, AsyncHTTPClient, _MAX_RESPONSE_BYTES
+from hyperneuronai.exceptions import APIError
+from hyperneuronai.types.tts import TTSRequest, TTSResponse, AudioFormat
+
+
+def _make_wav_bytes(pcm_f32_bytes: bytes, sample_rate: int) -> bytes:
+    """Convert raw float32-LE PCM bytes to a WAV file in memory."""
+    n_samples = len(pcm_f32_bytes) // 4
+    pcm_s16 = bytearray(n_samples * 2)
+    for i in range(n_samples):
+        sample_f32 = struct.unpack_from("<f", pcm_f32_bytes, i * 4)[0]
+        sample_s16 = max(-32768, min(32767, int(sample_f32 * 32767)))
+        struct.pack_into("<h", pcm_s16, i * 2, sample_s16)
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sample_rate)
+        wf.writeframes(bytes(pcm_s16))
+    return buf.getvalue()
+
+
+def _build_payload(request: TTSRequest) -> dict:
+    return request.model_dump(exclude_none=True)
+
+
+# ── Sync ──────────────────────────────────────────────────────────────────────
+
+
+class TTS:
+    """
+    Synchronous TTS resource.
+
+    Usage::
+
+        audio_bytes = client.tts.generate("Hello world", voice="sanjana")
+        with open("out.wav", "wb") as f:
+            f.write(audio_bytes)
+
+        for chunk in client.tts.stream("Hello world", voice="sanjana"):
+            speaker.play(chunk)
+    """
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def generate(
+        self,
+        text: str,
+        *,
+        voice: str = "sanjana",
+        language: Optional[str] = None,
+        temperature: float = 0.65,
+        repetition_penalty: float = 1.1,
+        top_p: float = 0.95,
+        max_tokens: int = 2000,
+        format: AudioFormat = "wav",
+        sample_rate: int = 24000,
+    ) -> bytes:
+        """
+        Generate speech and return the complete audio as bytes.
+
+        Returns WAV bytes by default (``format="wav"``).
+        Use ``format="pcm_f32le"`` or ``format="pcm_s16le"`` for raw PCM.
+        """
+        req = TTSRequest(
+            text=text,
+            voice=voice,
+            language=language,
+            temperature=temperature,
+            repetition_penalty=repetition_penalty,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            format=format,
+            sample_rate=sample_rate,
+        )
+        chunks: list[bytes] = []
+        total = 0
+        for chunk in self._http.stream_bytes("/tts/stream", json_body=_build_payload(req)):
+            total += len(chunk)
+            if total > _MAX_RESPONSE_BYTES:
+                raise APIError(
+                    f"TTS response exceeded {_MAX_RESPONSE_BYTES // (1024*1024)} MB limit.",
+                    status_code=0,
+                )
+            chunks.append(chunk)
+        raw = b"".join(chunks)
+        if format == "wav" and not raw.startswith(b"RIFF"):
+            raw = _make_wav_bytes(raw, sample_rate)
+        return raw
+
+    def stream(
+        self,
+        text: str,
+        *,
+        voice: str = "sanjana",
+        language: Optional[str] = None,
+        temperature: float = 0.65,
+        repetition_penalty: float = 1.1,
+        top_p: float = 0.95,
+        max_tokens: int = 2000,
+        sample_rate: int = 24000,
+    ) -> Iterator[bytes]:
+        """
+        Stream speech audio chunks as they are generated.
+
+        Yields raw PCM float32-LE bytes. First chunk typically arrives within 200 ms.
+        Useful for real-time playback where you want minimal latency.
+        """
+        req = TTSRequest(
+            text=text,
+            voice=voice,
+            language=language,
+            temperature=temperature,
+            repetition_penalty=repetition_penalty,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            format="pcm_f32le",
+            sample_rate=sample_rate,
+        )
+        yield from self._http.stream_bytes("/tts/stream", json_body=_build_payload(req))
+
+    def voices(self) -> list[dict]:
+        """Return available voices and their metadata."""
+        return self._http.get("/tts/voices")
+
+
+# ── Async ─────────────────────────────────────────────────────────────────────
+
+
+class AsyncTTS:
+    """
+    Async TTS resource.
+
+    Usage::
+
+        audio_bytes = await client.tts.generate("Hello world", voice="sanjana")
+
+        async for chunk in client.tts.stream("Hello world", voice="sanjana"):
+            await speaker.play(chunk)
+    """
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def generate(
+        self,
+        text: str,
+        *,
+        voice: str = "sanjana",
+        language: Optional[str] = None,
+        temperature: float = 0.65,
+        repetition_penalty: float = 1.1,
+        top_p: float = 0.95,
+        max_tokens: int = 2000,
+        format: AudioFormat = "wav",
+        sample_rate: int = 24000,
+    ) -> bytes:
+        """Generate speech and return the complete audio as bytes."""
+        req = TTSRequest(
+            text=text,
+            voice=voice,
+            language=language,
+            temperature=temperature,
+            repetition_penalty=repetition_penalty,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            format=format,
+            sample_rate=sample_rate,
+        )
+        chunks: list[bytes] = []
+        total = 0
+        async for chunk in self._http.stream_bytes("/tts/stream", json_body=_build_payload(req)):
+            total += len(chunk)
+            if total > _MAX_RESPONSE_BYTES:
+                raise APIError(
+                    f"TTS response exceeded {_MAX_RESPONSE_BYTES // (1024*1024)} MB limit.",
+                    status_code=0,
+                )
+            chunks.append(chunk)
+        raw = b"".join(chunks)
+        if format == "wav" and not raw.startswith(b"RIFF"):
+            raw = _make_wav_bytes(raw, sample_rate)
+        return raw
+
+    async def stream(
+        self,
+        text: str,
+        *,
+        voice: str = "sanjana",
+        language: Optional[str] = None,
+        temperature: float = 0.65,
+        repetition_penalty: float = 1.1,
+        top_p: float = 0.95,
+        max_tokens: int = 2000,
+        sample_rate: int = 24000,
+    ) -> AsyncIterator[bytes]:
+        """Stream speech audio chunks as they are generated."""
+        req = TTSRequest(
+            text=text,
+            voice=voice,
+            language=language,
+            temperature=temperature,
+            repetition_penalty=repetition_penalty,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            format="pcm_f32le",
+            sample_rate=sample_rate,
+        )
+        async for chunk in self._http.stream_bytes("/tts/stream", json_body=_build_payload(req)):
+            yield chunk
+
+    async def voices(self) -> list[dict]:
+        """Return available voices and their metadata."""
+        return await self._http.get("/tts/voices")

hyperneuronai/types/__init__.py

@@ -0,0 +1,18 @@
+from hyperneuronai.types.tts import TTSRequest, TTSResponse, AudioFormat, Voice
+from hyperneuronai.types.telephony import (
+    CallRequest,
+    CallResponse,
+    CallStatus,
+    CallState,
+)
+
+__all__ = [
+    "TTSRequest",
+    "TTSResponse",
+    "AudioFormat",
+    "Voice",
+    "CallRequest",
+    "CallResponse",
+    "CallStatus",
+    "CallState",
+]

hyperneuronai/types/telephony.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import re
+from typing import Literal, Optional
+from pydantic import BaseModel, Field, field_validator
+
+
+CallState = Literal["queued", "ringing", "in_progress", "completed", "failed", "cancelled"]
+
+_E164_RE = re.compile(r"^\+[1-9]\d{6,14}$")
+
+
+class OutboundCallRequest(BaseModel):
+    """Request model for a one-way outbound call."""
+
+    to: str = Field(..., description="E.164 phone number, e.g. '+919876543210'.")
+    text: str = Field(..., min_length=1, max_length=4096, description="Message text to synthesize and deliver.")
+    voice: str = Field(default="sanjana")
+    language: str = Field(default="en", description="BCP-47 language code or 'auto'.")
+    metadata: dict = Field(
+        default_factory=dict,
+        description="Arbitrary key/value pairs for your own tracking.",
+    )
+
+    @field_validator("to")
+    @classmethod
+    def _validate_e164(cls, v: str) -> str:
+        if not _E164_RE.match(v):
+            raise ValueError(
+                f"Phone number must be in E.164 format (e.g. '+919876543210'), got {v!r}."
+            )
+        return v
+
+
+class CallResponse(BaseModel):
+    call_uuid: str
+    state: CallState
+    to: str
+    voice: str
+    created_at: str
+
+
+class CallStatus(BaseModel):
+    call_uuid: str
+    state: CallState
+    to: str
+    duration_seconds: Optional[float] = None
+    started_at: Optional[str] = None
+    ended_at: Optional[str] = None

hyperneuronai/types/tts.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Literal, Optional
+from pydantic import BaseModel, Field
+
+
+Voice = Literal[
+    "sanjana", "arjun", "priya", "rahul", "ananya",
+    "leela", "dev", "kavya", "rohan", "meera",
+]
+
+AudioFormat = Literal["wav", "pcm_f32le", "pcm_s16le"]
+
+
+class TTSRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=4096)
+    voice: str = Field(default="sanjana")
+    language: Optional[str] = Field(default=None, description="BCP-47 language tag, e.g. 'en', 'hi'. None = auto.")
+    temperature: float = Field(default=0.65, ge=0.0, le=1.0)
+    repetition_penalty: float = Field(default=1.1, ge=1.0, le=2.0)
+    top_p: float = Field(default=0.95, ge=0.0, le=1.0)
+    max_tokens: int = Field(default=2000, ge=7, le=4096)
+    format: AudioFormat = Field(default="wav")
+    sample_rate: int = Field(default=24000, ge=8000, le=48000, description="Output sample rate in Hz.")
+
+
+class TTSResponse(BaseModel):
+    audio: bytes = Field(..., description="Raw audio bytes in the requested format.")
+    format: AudioFormat
+    sample_rate: int
+    duration_seconds: float
+    voice: str
+    text: str

hyperneuronai-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: hyperneuronai
+Version: 0.1.0
+Summary: Official Python SDK for HyperNeuron AI services
+Author-email: HyperNeuron AI <support@hyperneuron.in>
+License: MIT
+Project-URL: Homepage, https://www.hyperneuronai.com
+Project-URL: Repository, https://github.com/hyperneuronai/hyperneuronai-python
+Keywords: ai,tts,voice,telephony,speech
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: audio
+Requires-Dist: numpy>=1.24.0; extra == "audio"
+Requires-Dist: scipy>=1.11.0; extra == "audio"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# hyperneuronai
+
+Official Python SDK for [HyperNeuron AI](https://www.hyperneuronai.com) — TTS streaming and AI telephony services.
+
+## Install
+
+```bash
+pip install hyperneuronai
+```
+
+## Quick start
+
+```python
+import hyperneuronai
+
+client = hyperneuronai.HyperNeuron(
+    api_key="hn_key_xxxx",
+    base_url="https://api.hyperneuronai.com",
+)
+
+# TTS — save to WAV
+audio = client.tts.generate("Hello, world!", voice="sanjana")
+with open("hello.wav", "wb") as f:
+    f.write(audio)
+
+# TTS — stream in real time
+for chunk in client.tts.stream("Hello, world!", voice="sanjana"):
+    your_speaker.write(chunk)
+
+# One-way outbound call
+call = client.telephony.outbound(
+    to="+919876543210",
+    text="Hi! Your order has shipped and arrives tomorrow.",
+    voice="sanjana",
+)
+print(call.call_uuid, call.state)
+```
+
+## Async
+
+```python
+import asyncio
+import hyperneuronai
+
+async def main():
+    async with hyperneuronai.AsyncHyperNeuron(api_key="hn_key_xxxx") as client:
+        audio = await client.tts.generate("Hello!")
+        call  = await client.telephony.outbound(to="+919876543210", text="Hi there!")
+
+asyncio.run(main())
+```
+
+## License
+
+MIT

hyperneuronai-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+hyperneuronai/__init__.py,sha256=YeAaaZswLSheb6k0eUV5qw8tiUtpice5uK7c17-TwaQ,1998
+hyperneuronai/_client.py,sha256=FOIJDKMtuTUCJpRSUEzS8gW9nWqHKhT0n3ckb03uERg,7067
+hyperneuronai/_hyperneuron.py,sha256=gae06ROvWfNbTZgQ8uIuNRW6MKKQZMOmVOcB60om2Us,3357
+hyperneuronai/exceptions.py,sha256=REWc2HMZobLSsP_rLVOpJymKkgL4swCyL3WbdIziBBA,1554
+hyperneuronai/resources/__init__.py,sha256=04T8MvigZEs7fUGTqZ4iuVAc93a6fHiXUNdeyO-fqFk,188
+hyperneuronai/resources/telephony.py,sha256=sevXFgBpbAo1a2PGluw8XxcZ3w-6pJNmh0vHohERq_Y,6323
+hyperneuronai/resources/tts.py,sha256=qihODFU3Ig0fDooGoSAKsBhNwbXnNBHwUwhXDkAXN_8,7307
+hyperneuronai/types/__init__.py,sha256=L8Eh19U3sYacf4-2k36CIVF50_MMOwjw4XOGm_QC9rE,350
+hyperneuronai/types/telephony.py,sha256=7ez3OXZ6UBf-Jb0kOgtP7PC8kH6Lw0jUYnFHXWu6Wt4,1426
+hyperneuronai/types/tts.py,sha256=BHex7PtAqua7uUYNktM8s4go0nVIi25-AJfyVEogA_0,1145
+hyperneuronai-0.1.0.dist-info/METADATA,sha256=Eu7eAs5zGmNwfpExHxaEFHQ7MZRBj8HhMgyu6D-uOwc,2366
+hyperneuronai-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hyperneuronai-0.1.0.dist-info/top_level.txt,sha256=vbmotorGV8rzApWbwPNFN-GvnTK5-JBSXnxjY0jXQ70,14
+hyperneuronai-0.1.0.dist-info/RECORD,,

hyperneuronai-0.1.0.dist-info/WHEEL

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

hyperneuronai-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hyperneuronai