Skip to main content

newera-sdk

test

Speech-to-speech calls with tool calling, in Python. Newera listens, talks (Saudi Arabic and English) and decides when to call your functions; you write the functions.

import asyncio
from newera import VoiceAgent

agent = VoiceAgent(api_key="nwc_live_...", instructions="You book clinic appointments.", voice="male")

@agent.tool
def get_free_slots(date: str) -> list[str]:
    """Free appointment times on a day.

    Args:
        date: The day, as YYYY-MM-DD.
    """
    return ["09:00", "10:30"]

@agent.tool(requires_confirmation=True, timeout_ms=20000)
async def book_appointment(patient_name: str, date: str, time: str) -> dict:
    """Book an appointment."""
    return {"booking_id": "B-1"}

async def main():
    async with agent.connect() as call:
        await call.send_text("I need an appointment on Saturday")
        reply = await call.wait_response()
        print(reply.transcript)          # tools ran while it waited

asyncio.run(main())

A complete agent with a mock clinic: examples/clinic_agent.py.

Install

pip install newera-sdk

The import name is newera: from newera import VoiceAgent.

It needs Python 3.9 or newer and depends only on websockets.

Tools

@agent.tool turns a function into a tool. The schema comes from the function:

from becomes
the name tool name (name= overrides)
docstring summary (text before a blank line or Args:) description (description= overrides)
Args: section, Google style (name: text or name (type): text) each parameter's description
str, int, float, bool string, integer, number, boolean
Literal["a", "b"], Enum enum
Optional[X], X | None, parameters with a default optional (not in required)
list[X], dict, Union[...], Any array, object, anyOf, any value
@agent.tool(requires_confirmation=False, timeout_ms=15000)
def my_tool(...): ...

Both sync and async functions work (sync ones run in a thread, so a slow call never blocks the audio). The return value is JSON encoded and given to the model (dates, decimals, enums and dataclasses are converted). If the function raises, the model receives {"error": "ValueError: ..."} and tells the caller; the call carries on.

What Newera does around your function

  • Validation. The model's arguments are checked against the schema before your function is called. A wrong or missing argument never reaches you: the model is told and asks the caller.
  • Confirmation. With requires_confirmation=True, your function is called only after the assistant read the details back and the caller said yes. A different argument is a new question. Declare every function that changes something this way (booking, paying, cancelling, sending).
  • Speech while you work. If the model calls a tool without saying anything, Newera speaks a short line ("Sure, one moment while I check...") and, if your function takes more than 3 and 8 seconds, a progress line. You write nothing for this.
  • Timeouts. timeout_ms (1000 to 60000, default 15000) is how long Newera waits for the result; after that the model tells the caller it is taking longer and offers to retry.
  • Barge-in. If the caller interrupts while a read-only tool runs, it is cancelled (an asyncio cancel for async functions; a sync function in a thread cannot be stopped, but its result is ignored). A tool with requires_confirmation is never cancelled; its result is reported truthfully on the next turn.
  • Limits. At most 32 tools; each name ^[a-zA-Z0-9_-]{1,64}$; each schema 16 KB, all of them 64 KB; a result is cut at 32 KB; at most 6 tool steps per reply (VoiceAgent(max_tool_steps=...), up to 10). When the limit is reached the assistant tells the caller what is done and asks whether to continue.

Treat what your functions return as what the model will read to the caller, and treat what comes back from a tool as data, never as instructions.

The call

async with agent.connect() as call:
    await call.send_audio(pcm16_bytes)      # 16-bit mono, 24 kHz by default (16 kHz: session={"newera": {"input_audio_sample_rate": 16000}}); real time, 20-100 ms chunks
    await call.send_text("hello")           # a typed turn (add respond=False to wait)
    await call.say("Welcome to the clinic") # the assistant speaks first
    async for event in call:                # every server event
        ...
    await call.end()                        # session.summary, then the call closes

event.type is the protocol's event name (protocol reference): response.audio.delta (event.audio gives the PCM16 24 kHz bytes), response.audio_transcript.delta, input_audio_buffer.speech_started (stop your playback), response.done, error, and so on. The SDK adds one event, sdk.tool_result (name, arguments, output, error, ms), after each of your functions ran.

await call.wait_response() collects events up to the next response.done and returns a Reply(transcript, audio, status, usage, events); handy for text-only scripts and tests.

VoiceAgent(...) takes api_key, instructions, voice, tool_choice ("auto", "none", "required", or {"type": "function", "name": ...}), max_tool_steps, auto_continue, llm ("newera-chat-large", the default, or "newera-chat-small": the fastest first word and the lowest cost), session (extra session.update fields such as {"tts": {"quality": "studio"}}), url and headers.

auto_continue=False is the OpenAI-style flow: after your outputs the SDK sends response.create itself and the server does not continue on its own.

Browsers must not hold an API key: this SDK is for servers. Give browser clients their own short-lived credentials instead.

Tests

pip install -e '.[test]' && pytest

The tests run the SDK against a fake WebSocket server; no network, no key.

Releasing

  1. Bump version in pyproject.toml (and __version__ in src/newera/__init__.py).
  2. Push to main. The publish workflow runs the tests. If that version is not yet on PyPI, it builds the package, uploads it through trusted publishing, and creates the vX.Y.Z tag and a GitHub Release. No API token is stored in the repository.
  3. A push with an unchanged version only runs the tests.

License

Apache License 2.0. See LICENSE.

Metadata

Release files for newera-sdk 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for newera-sdk 0.1.2
File Size Uploaded Provenance Actions
newera_sdk-0.1.2.tar.gz 21.1 kB With provenance Details for newera_sdk-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for newera-sdk 0.1.2
File Interpreter ABI Platform Actions
newera_sdk-0.1.2-py3-none-any.whl Python 3 none any Details for newera_sdk-0.1.2-py3-none-any.whl

Total release size: 37.2 kB

Release files / newera_sdk-0.1.2.tar.gz

Download URL newera_sdk-0.1.2.tar.gz
Size 21.1 kB
Tags Source
SHA-256 checksum
How to use checksums
848c95f1e7003b843970ae9e947e2b48158411326953a7ccccf6bbeca4615494
BLAKE2b-256 checksum
How to use checksums
79f3a1301eefbce148708fb2d1e4bd7c2289cb88a0077652c924a32f2ada2b2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / newera_sdk-0.1.2-py3-none-any.whl

Download URL newera_sdk-0.1.2-py3-none-any.whl
Size 16.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
76e9fa6ff99edcedf47ad5c206f02df796f18bb807640abeb6942c6b6f2eeeee
BLAKE2b-256 checksum
How to use checksums
ff1e32c66f66bfb473180434b5415977c0edef23d8413941de03e3fc57f3545f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for newera-sdk 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for newera_sdk-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page