hyperneuronai 0.2.0

Official Python SDK for HyperNeuron AI services

hyperneuronai

Official Python SDK for HyperNeuron AI — streaming TTS, one-way voice broadcasts, and full-duplex agentic AI phone calls.

Install

pip install hyperneuronai

Client setup

import hyperneuronai

client = hyperneuronai.HyperNeuron(
    api_key="<api-key-from-your-account>",
    base_url="https://ai.hyperneuron.in",
)

Available voices: sanjana, divya, elina, deepraj, raju.

---

Text-to-Speech

POST /tts/stream. Audio is 16-bit little-endian PCM; generate(format="wav") wraps it in a ready-to-save WAV container.

# Save a complete WAV file
audio = client.tts.generate("Hello! How are you today?", voice="deepraj")
with open("hello.wav", "wb") as f:
    f.write(audio)

# Raw 16-bit PCM (no header) — e.g. to pipe into telephony
pcm = client.tts.generate("नमस्ते", voice="sanjana", format="pcm", sample_rate=8000)

# Stream chunks for low-latency playback (each chunk is int16 PCM)
for chunk in client.tts.stream("Hello, world!", voice="elina"):
    your_speaker.write(chunk)

# List voices (served locally by the SDK)
print(client.tts.voices())

text is capped at 2000 characters. sample_rate may be 8000–48000 Hz (default 24000).

---

One-way outbound call

Synthesizes text and plays it to the recipient — the called party cannot speak back.

call = client.telephony.outbound(
    to_number="+91xxxxxxxxx",
    text="Hi! Your order has shipped and arrives tomorrow.",
    voice="sanjana",
    language="en",
    from_number="+91xxxxxxxx",  
)
print(call.call_uuid, call.state)

---

Two-way agentic call

A full-duplex AI voice conversation: the recipient speaks and the AI responds in real time. Configure the agent inline, or reference a saved agent by agent_id (see below). Inline fields override the saved config for that call.

# Inline configuration
call = client.telephony.agent_call(
    to_number="+91xxxxx-xxxxx",
    greeting="Hi! This is HyperNeuron calling. How can I help you today?",
    system="You are a friendly support agent. Keep replies short.",
    voice="deepraj",
    language="hi",
    country_code="IN",
    knowledge_base_id=None,           # optional RAG knowledge base
    barge_in_min_duration_ms=0,       # 0 = caller can interrupt immediately
    speaker_voice_energy_threshold=0.009,
    speaker_silence_threshold_ms=280,
)

# …or use a saved agent
call = client.telephony.agent_call(to_number="+91xxxxx-xxxxx", agent_id=agent.agent_id)

print(f"Call initiated: {call.call_uuid} ({call.state})")

Track the call until it ends

The event stream is push-based, so follow it over one live connection with stream_events() rather than polling. The loop ends by itself when the call finishes:

for ev in client.telephony.stream_events(call.call_uuid):
    print(f"  → {ev.state}")
    if ev.is_terminal:
        print(f"Call ended: {ev.state}")
        if ev.duration_sec:
            print(f"Duration: {ev.duration_sec}s ({ev.duration_min:.1f} min)")

client.close()

Don't poll status() in a while loop. A fresh connection only replays a connected handshake plus future events, so polling can't observe the call ending and will spin or block. status() is only a one-shot snapshot.

---

Saved agents

Create reusable agent configurations (system prompt, voice, VAD tuning, human-handoff rules) and start calls against them with agent_id.

agent = client.agents.create(
    name="Support Bot",
    system_prompt="You are a friendly support agent. Keep replies short.",
    greeting="Hi! Thanks for calling HyperNeuron support.",
    voice="deepraj",
    language="hi",
    speaker_silence_threshold_ms=280,
    human_agent_numbers=[
        {"phone_number": "+91xxxxx-xxxxx", "priority": 1, "label": "Tier 1"},
    ],
    dtmf_handoff_keys=["0"],
)
print(agent.agent_id)

# List / fetch / update / delete
agents = client.agents.list()
agent = client.agents.get(agent.agent_id)
agent = client.agents.update(agent.agent_id, voice="elina", greeting="नमस्ते!")
client.agents.delete(agent.agent_id)

# Start a call with the saved agent
client.telephony.agent_call(to_number="+91xxxxx-xxxxx", agent_id=agent.agent_id)

Only name is required on create(); every other field falls back to the server default.

---

Async

Every method exists on AsyncHyperNeuron with the same signature.

import asyncio
import hyperneuronai

async def main():
    async with hyperneuronai.AsyncHyperNeuron(api_key="<api-key>") as client:
        audio = await client.tts.generate("Hello!", voice="deepraj")

        agent = await client.agents.create(name="Sales Bot", voice="sanjana")

        call = await client.telephony.agent_call(
            to_number="+91xxxxx-xxxxx",
            agent_id=agent.agent_id,
        )

        async for chunk in client.tts.stream("Streaming hello"):
            ...  # each chunk is int16 PCM

asyncio.run(main())

---

Error handling

from hyperneuronai import (
    AuthenticationError, RateLimitError, NotFoundError, APIConnectionError, APIError,
)

try:
    call = client.telephony.agent_call(to_number="[phone]")
except AuthenticationError:
    ...   # bad / missing API key
except RateLimitError:
    ...   # slow down
except APIError as exc:
    print(exc.status_code, exc)

License

MIT