sonara-client 0.21.7__py3-none-any.whl

sonara_client/__init__.py

@@ -0,0 +1,35 @@
+"""sonara-client: talk to the Sonara runtime (protocol v1). Standard library only.
+
+    import sonara_client
+
+    with sonara_client.connect("my-app", runtime_path=r"C:\\path\\to\\sonarad.exe") as sonara:
+        item = sonara.speak("Hello.")
+        for event in sonara.subscribe(["items"]):
+            if event["item_id"] == item and event["phase"] != "started":
+                break
+"""
+from __future__ import annotations
+
+from .client import Client, Subscription
+from .connect import connect
+from .discovery import read_runtime, resolve_home
+from .engines import SEND_MODES, Engines
+from .errors import SonaraError
+from .extensions import Agent, Channels, System
+from .version import PROTOCOL, __version__
+
+__all__ = [
+    "Agent",
+    "Channels",
+    "Client",
+    "Engines",
+    "PROTOCOL",
+    "SEND_MODES",
+    "SonaraError",
+    "Subscription",
+    "System",
+    "__version__",
+    "connect",
+    "read_runtime",
+    "resolve_home",
+]

sonara_client/client.py

@@ -0,0 +1,136 @@
+"""The connected client and its event subscriptions."""
+from __future__ import annotations
+
+import socket
+from typing import Any, Callable, Iterator, List, Optional, Sequence
+
+from .connection import Connection
+from .errors import E_CLOSED, SonaraError
+from .engines import Engines
+from .extensions import Agent, Channels, System
+
+ALL_EVENTS = ("state", "items", "log")
+
+
+class Subscription:
+    """Events on a connection of their own: iterate it, or ``read()`` with a
+    timeout. Each event is a dict whose ``event`` is ``state``, ``item`` or
+    ``log``. Iteration ends when the runtime closes the connection."""
+
+    def __init__(self, conn: Connection):
+        self._conn = conn
+
+    def __iter__(self) -> Iterator[dict]:
+        return self
+
+    def __next__(self) -> dict:
+        event = self._conn.next_event(None)
+        if event is None:
+            raise StopIteration
+        return event
+
+    def read(self, timeout: Optional[float] = None) -> Optional[dict]:
+        """The next event, or None when none arrived within ``timeout``
+        seconds. SonaraError ``E_CLOSED`` once the stream ended."""
+        try:
+            event = self._conn.next_event(timeout)
+        except socket.timeout:
+            return None
+        if event is None:
+            raise SonaraError(E_CLOSED, "the event stream ended")
+        return event
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> "Subscription":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class Client:
+    """A connected Sonara client (see ``connect``). Thread-safe: requests on
+    the shared connection run one at a time."""
+
+    def __init__(self, conn: Connection, runtime: dict, info: dict, dial: Callable[[], Connection]):
+        self._conn = conn
+        self._dial = dial
+        self._subs: List[Subscription] = []
+        #: ``runtime.json`` of the instance this client talks to.
+        self.runtime = runtime
+        #: The ``hello`` reply: version, protocol, capabilities, extensions, unavailable.
+        self.info = info
+        self.channels = Channels(self.request)
+        self.agent = Agent(self.request)
+        self.system = System(self.request)
+        self.engines = Engines(self.request)
+
+    @property
+    def closed(self) -> bool:
+        return self._conn.closed
+
+    def request(self, type_: str, fields: Optional[dict] = None) -> dict:
+        """Send any protocol message; the ``ok: true`` reply."""
+        return self._conn.request(type_, fields)
+
+    def speak(self, text: str, mode: Optional[str] = None, interrupt: Optional[bool] = None,
+              label: Optional[str] = None) -> int:
+        """Add ``text`` as one item; its item id. ``mode``: ``append``
+        (default) or ``replace``; ``interrupt`` also cuts the current item."""
+        fields: dict = {"text": text}
+        if mode is not None:
+            fields["mode"] = mode
+        if interrupt is not None:
+            fields["interrupt"] = interrupt
+        if label is not None:
+            fields["label"] = label
+        return self.request("speak", fields)["item_id"]
+
+    def control(self, action: str) -> None:
+        """play, pause, toggle, stop, skip, previous, next, restart, mute, unmute."""
+        self.request("control", {"action": action})
+
+    def set(self, key: str, value: Any) -> Any:
+        """Change ``volume``, ``rate``, ``voice`` or ``engine``; the value now in force."""
+        return self.request("set", {"key": key, "value": value})["value"]
+
+    def get(self, key: str) -> Any:
+        """Read a setting."""
+        return self.request("get", {"key": key})["value"]
+
+    def voices(self, engine: Optional[str] = None, refresh: bool = False) -> list:
+        """Voices of one engine, or of all. ``refresh`` asks an external
+        engine's provider again (protocol 1.2)."""
+        fields: dict = {} if engine is None else {"engine": engine}
+        if refresh:
+            fields["refresh"] = True
+        return self.request("voices", fields)["voices"]
+
+    def subscribe(self, events: Sequence[str] = ALL_EVENTS) -> Subscription:
+        """Open an event stream (``state``, ``items``, ``log``) on a new
+        connection. When ``state`` is included the first event is the
+        current state."""
+        conn = self._dial()
+        try:
+            conn.request("subscribe", {"events": list(events)})
+        except SonaraError:
+            conn.close()
+            raise
+        sub = Subscription(conn)
+        self._subs.append(sub)
+        return sub
+
+    def close(self) -> None:
+        """Close this client's connections. The runtime keeps running for
+        other clients and exits on its own when idle."""
+        for sub in self._subs:
+            sub.close()
+        self._conn.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

sonara_client/connect.py

@@ -0,0 +1,164 @@
+"""``connect()``: find or start the shared runtime (spec section 3)."""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional, Sequence
+
+from .client import Client
+from .connection import Connection
+from .discovery import live_runtime, resolve_home, start_runtime, wait_exit
+from .errors import E_CLOSED, E_NOT_RUNNING, SonaraError
+from .version import PROTOCOL, __version__
+
+CONNECT_TIMEOUT = 5.0
+EXIT_WAIT = 5.0
+
+
+class _Incompatible(Exception):
+    """The instance answers but cannot serve this client."""
+
+
+def connect(
+    client_name: str,
+    *,
+    runtime_path: Optional[str] = None,
+    home: Optional[str] = None,
+    autostart: bool = True,
+    require: Sequence[str] = (),
+    extensions: Sequence[str] = (),
+    client_version: Optional[str] = None,
+    keep_alive: bool = False,
+    runtime_args: Sequence[str] = (),
+    start_timeout: float = 5.0,
+    takeover_timeout: float = 30.0,
+    takeover_retry: float = 0.25,
+    timeout: float = 10.0,
+) -> Client:
+    """Connect to the shared Sonara runtime.
+
+    1. Read ``runtime.json`` in the home (``home``, else ``SONARA_HOME``,
+       else ``%LOCALAPPDATA%\\Sonara``); when its pid is alive, connect and
+       send ``hello``.
+    2. Use it when it speaks protocol 1 and offers everything in ``require``.
+    3. Otherwise (with ``autostart``), start ``runtime_path --home <home>``
+       (default: ``SONARA_RUNTIME``), wait up to ``start_timeout`` seconds
+       for its ``runtime.json``, then ``hello``.
+    4. An incompatible running instance is first asked to step down
+       (``hello`` with ``takeover: true``); while it is busy the takeover is
+       retried for up to ``takeover_timeout`` seconds, then
+       ``E_INCOMPATIBLE``.
+
+    ``runtime_args`` are extra arguments for a started runtime (tests:
+    ``["--engine", "fake"]``); ``timeout`` bounds each request.
+    """
+    if not isinstance(client_name, str) or not client_name:
+        raise SonaraError("E_BAD_REQUEST", "connect() needs a client_name")
+    home = resolve_home(home)
+    runtime_path = runtime_path or os.environ.get("SONARA_RUNTIME")
+    can_start = bool(autostart and runtime_path)
+    hello = {
+        "client": {"name": client_name, "version": client_version or __version__},
+        "protocol": dict(PROTOCOL),
+        "require": list(require),
+        "extensions": list(extensions),
+    }
+    if keep_alive:
+        hello["keep_alive"] = True
+
+    running = live_runtime(home)
+    if running:
+        try:
+            client = _greet(running, hello, list(require), timeout)
+            if client:
+                return client
+        except _Incompatible as e:
+            if not can_start:
+                raise SonaraError(
+                    "E_INCOMPATIBLE",
+                    f"the running Sonara {running.get('version')} cannot serve this client ({e}) "
+                    "and there is no runtime to start in its place",
+                ) from None
+            _take_over(home, client_name, client_version, str(e), takeover_timeout, takeover_retry)
+
+    if not can_start:
+        why = "autostart is off" if runtime_path else "no runtime_path to start one"
+        raise SonaraError(E_NOT_RUNNING, f"no Sonara runtime is running and {why}")
+    started = start_runtime(runtime_path, home, list(runtime_args), start_timeout)
+    try:
+        client = _greet(started, hello, list(require), timeout)
+    except _Incompatible as e:
+        raise SonaraError(
+            "E_INCOMPATIBLE", f"the bundled Sonara {started.get('version')} cannot serve this client: {e}"
+        ) from None
+    if client is None:
+        raise SonaraError(E_CLOSED, "the started runtime closed the connection")
+    return client
+
+
+def _greet(info: dict, hello: dict, require: list, timeout: float) -> Optional[Client]:
+    """Connect and ``hello``. None when the instance cannot be reached;
+    _Incompatible when it answers but cannot serve this client."""
+
+    def dial() -> Connection:
+        conn = Connection(info["port"], timeout)
+        try:
+            conn.request("hello", {**hello, "token": info["token"]})
+        except SonaraError:
+            conn.close()
+            raise
+        return conn
+
+    try:
+        conn = Connection(info["port"], min(timeout, CONNECT_TIMEOUT))
+    except SonaraError:
+        return None
+    try:
+        reply = conn.request("hello", {**hello, "token": info["token"]})
+    except SonaraError as e:
+        conn.close()
+        if e.code in ("E_INCOMPATIBLE", "E_UNSUPPORTED"):
+            raise _Incompatible(e.message) from None
+        if e.code == E_CLOSED:
+            return None
+        raise
+    offered = set(reply.get("capabilities") or []) | set(reply.get("extensions") or [])
+    missing = [r for r in require if r not in offered]
+    major = (reply.get("protocol") or {}).get("major")
+    if major != PROTOCOL["major"] or missing:
+        conn.close()
+        raise _Incompatible(f"it does not offer {', '.join(missing)}" if missing else f"it speaks protocol {major}")
+    return Client(conn, info, reply, dial)
+
+
+def _take_over(home: str, name: str, version: Optional[str], why: str, limit: float, retry: float) -> None:
+    """Ask the running instance to exit so the bundled runtime can start. It
+    accepts only when idle; while busy, retry until ``limit`` seconds. Each
+    attempt uses a fresh connection: the runtime closes one that has no
+    successful ``hello`` within 5 s."""
+    deadline = time.monotonic() + limit
+    client = {"name": name, "version": version or __version__}
+    while True:
+        cur = live_runtime(home)
+        if not cur:
+            return
+        try:
+            conn = Connection(cur["port"], CONNECT_TIMEOUT)
+            try:
+                conn.request("hello", {"token": cur["token"], "client": client, "takeover": True})
+            finally:
+                conn.close()
+            if wait_exit(cur["pid"], EXIT_WAIT):
+                return
+        except SonaraError as e:
+            if e.code not in ("E_BUSY", E_CLOSED):
+                raise SonaraError(
+                    "E_INCOMPATIBLE",
+                    f"the running Sonara cannot serve this client ({why}) and refused a takeover: {e.message}",
+                ) from None
+        if time.monotonic() >= deadline:
+            raise SonaraError(
+                "E_INCOMPATIBLE",
+                f"the running Sonara cannot serve this client ({why}) and stayed busy; gave up the takeover",
+            )
+        time.sleep(retry)

sonara_client/connection.py

@@ -0,0 +1,118 @@
+"""One TCP JSON-lines connection to the runtime."""
+from __future__ import annotations
+
+import itertools
+import json
+import socket
+import threading
+from typing import Optional
+
+from .errors import E_CLOSED, SonaraError
+
+MAX_LINE = 1 << 20
+
+
+class Connection:
+    """Requests and their replies (blocking, one at a time), plus events
+    for a subscribed connection."""
+
+    def __init__(self, port: int, timeout: float):
+        try:
+            self._sock = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+        except OSError as e:
+            raise SonaraError(E_CLOSED, f"cannot connect to 127.0.0.1:{port}: {e}") from None
+        self._sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        self._timeout = timeout
+        self._buf = b""
+        self._ids = itertools.count(1)
+        self._lock = threading.Lock()
+        self._events: list = []
+        self.closed = False
+
+    def request(self, type_: str, fields: Optional[dict] = None) -> dict:
+        """Send ``{type, **fields}``; the ``ok: true`` reply, or SonaraError."""
+        with self._lock:
+            if self.closed:
+                raise SonaraError(E_CLOSED, "the connection is closed")
+            msg = dict(fields or {})
+            msg["type"] = type_
+            msg["id"] = next(self._ids)
+            try:
+                self._sock.sendall(json.dumps(msg).encode("utf-8") + b"\n")
+            except OSError as e:
+                self._mark_closed()
+                raise SonaraError(E_CLOSED, f"send failed: {e}") from None
+            while True:
+                try:
+                    reply = self._read(self._timeout)
+                except socket.timeout:
+                    # A late reply would answer the next request: give up
+                    # on this connection instead.
+                    self._mark_closed()
+                    raise SonaraError(E_CLOSED, f"no reply within {self._timeout} s") from None
+                if reply is None:
+                    raise SonaraError(E_CLOSED, "the connection closed before the reply")
+                if "event" in reply:
+                    self._events.append(reply)
+                    continue
+                if "ok" not in reply:
+                    continue
+                if reply.get("ok") is True:
+                    return reply
+                err = reply.get("error") or {}
+                raise SonaraError(err.get("code", "E_BAD_REQUEST"), err.get("message", "request failed"),
+                                  err.get("reason"))
+
+    def next_event(self, timeout: Optional[float]) -> Optional[dict]:
+        """The next event; None at the end of the stream. ``socket.timeout``
+        (``TimeoutError``) when none arrived within ``timeout`` seconds."""
+        if self._events:
+            return self._events.pop(0)
+        while True:
+            msg = self._read(timeout)
+            if msg is None or "event" in msg:
+                return msg
+
+    def close(self) -> None:
+        self._mark_closed()
+
+    def _mark_closed(self) -> None:
+        if not self.closed:
+            self.closed = True
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+
+    def _read(self, timeout: Optional[float]) -> Optional[dict]:
+        """The next JSON object line, or None once the stream ended."""
+        while True:
+            nl = self._buf.find(b"\n")
+            if nl >= 0:
+                line, self._buf = self._buf[:nl], self._buf[nl + 1:]
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    msg = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(msg, dict):
+                    return msg
+                continue
+            if self.closed:
+                return None
+            self._sock.settimeout(timeout)
+            try:
+                chunk = self._sock.recv(65536)
+            except socket.timeout:
+                raise
+            except OSError:
+                chunk = b""
+            if not chunk:
+                self._mark_closed()
+                return None
+            self._buf += chunk
+            if len(self._buf) > MAX_LINE * 2:
+                self._mark_closed()
+                return None

sonara_client/discovery.py

@@ -0,0 +1,147 @@
+"""Find, check and start the runtime (protocol v1, Discovery)."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from typing import Optional, Sequence
+
+from .errors import E_NOT_RUNNING, E_START_FAILED, SonaraError
+
+# Exit code of a second sonarad for the same user and home.
+EXIT_ALREADY_RUNNING = 3
+POLL = 0.05
+CREATE_NO_WINDOW = 0x08000000
+CREATE_NEW_PROCESS_GROUP = 0x00000200
+
+# Started runtimes outlive this process (they are shared and exit on their
+# own when idle). Holding the Popen objects keeps Python from warning that a
+# child is still running when they are garbage collected.
+_started: list = []
+
+
+def resolve_home(home: Optional[str] = None, env=None) -> str:
+    """``home``, else ``SONARA_HOME``, else ``%LOCALAPPDATA%\\Sonara``."""
+    env = os.environ if env is None else env
+    if home:
+        return str(home)
+    if env.get("SONARA_HOME"):
+        return env["SONARA_HOME"]
+    if env.get("LOCALAPPDATA"):
+        return os.path.join(env["LOCALAPPDATA"], "Sonara")
+    raise SonaraError(E_NOT_RUNNING, "no home folder: pass home, or set SONARA_HOME or LOCALAPPDATA")
+
+
+def read_runtime(home: str) -> Optional[dict]:
+    """``runtime.json`` of ``home``, or None when missing or unreadable."""
+    try:
+        with open(os.path.join(home, "runtime.json"), encoding="utf-8") as f:
+            info = json.load(f)
+    except (OSError, ValueError):
+        return None
+    if not isinstance(info, dict):
+        return None
+    if not isinstance(info.get("pid"), int) or not isinstance(info.get("port"), int):
+        return None
+    if not isinstance(info.get("token"), str):
+        return None
+    return info
+
+
+def pid_alive(pid: int) -> bool:
+    """True while process ``pid`` exists."""
+    if not isinstance(pid, int) or pid <= 0:
+        return False
+    if os.name == "nt":
+        return _pid_alive_windows(pid)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _pid_alive_windows(pid: int) -> bool:
+    # Not os.kill(pid, 0): on Windows that terminates the process.
+    import ctypes
+    from ctypes import wintypes
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    k32.OpenProcess.restype = wintypes.HANDLE
+    k32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    k32.GetExitCodeProcess.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+    k32.CloseHandle.argtypes = [wintypes.HANDLE]
+    process_query_limited_information = 0x1000
+    still_active = 259
+    handle = k32.OpenProcess(process_query_limited_information, False, pid)
+    if not handle:
+        # Access denied: it exists but belongs to someone else.
+        return ctypes.get_last_error() == 5
+    try:
+        code = wintypes.DWORD()
+        if not k32.GetExitCodeProcess(handle, ctypes.byref(code)):
+            return True
+        return code.value == still_active
+    finally:
+        k32.CloseHandle(handle)
+
+
+def live_runtime(home: str) -> Optional[dict]:
+    """``runtime.json`` of ``home`` when its pid is alive."""
+    info = read_runtime(home)
+    return info if info and pid_alive(info["pid"]) else None
+
+
+def start_runtime(runtime_path: str, home: str, args: Sequence[str], timeout: float) -> dict:
+    """Start ``runtime_path --home <home> [args]`` without a console window
+    and wait up to ``timeout`` seconds for its ``runtime.json``. When another
+    client started one at the same moment (the new process exits with code
+    3), the other's ``runtime.json`` is used."""
+    kwargs: dict = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "close_fds": True,
+    }
+    if os.name == "nt":
+        # Its own process group, so a Ctrl+C in this console does not end
+        # a runtime other apps share.
+        kwargs["creationflags"] = CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP
+    else:
+        kwargs["start_new_session"] = True
+    # An absolute path: Windows does not find a relative one written with
+    # forward slashes ("sonara/sonarad.exe"), which Node's spawn accepts (#274).
+    exe = os.path.abspath(str(runtime_path))
+    try:
+        proc = subprocess.Popen([exe, "--home", str(home), *args], **kwargs)
+    except OSError as e:
+        raise SonaraError(E_START_FAILED, f"cannot start {runtime_path}: {e}") from None
+    _started.append(proc)
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        info = read_runtime(home)
+        if info and info["pid"] == proc.pid:
+            return info
+        code = proc.poll()
+        if code is not None:
+            if code != EXIT_ALREADY_RUNNING:
+                raise SonaraError(E_START_FAILED, f"{runtime_path} exited with code {code}")
+            other = live_runtime(home)
+            if other:
+                return other
+        time.sleep(POLL)
+    raise SonaraError(E_START_FAILED, f"{runtime_path} wrote no runtime.json within {timeout} s")
+
+
+def wait_exit(pid: int, timeout: float) -> bool:
+    """Wait until process ``pid`` has ended; False if it still runs."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not pid_alive(pid):
+            return True
+        time.sleep(POLL)
+    return not pid_alive(pid)

sonara_client/engines.py

@@ -0,0 +1,110 @@
+"""External engines (protocol 1.2, capability ``engines``): speech engines
+the user adds at run time, such as OpenAI or a local OpenAI-compatible
+server.
+
+Each method sends one core message as is. The profile is named by the
+``engine`` field (a request's ``id`` is its correlation id). A runtime that
+refuses external engines (``sonarad --no-external-engines``) answers
+``E_UNSUPPORTED``. A key is sent only in ``add`` (``secret``) or
+``set_key`` (or with a draft profile in ``models``, for that request only);
+the runtime stores it in Windows Credential Manager and never returns it.
+
+Sonara names no model or voice of its own (protocol 1.5, runtime 0.19.0):
+``models`` and ``voices`` list the provider's live, and a profile without
+one it needs says so in ``engine_list`` (``missing``).
+
+"Send to the engine" (``send_mode`` of a profile, runtime 0.19.0, #235):
+``"message"`` sends a whole released message in one request (the default of
+the cloud kinds), ``"sentence"`` each sentence as it comes (the default of a
+program and a server on this PC). The view in ``engine_list`` tells the mode
+in force, and ``explicit["send_mode"]`` whether the profile chose it.
+
+A ``command`` engine (a program on the user's PC) is never added or changed
+through the protocol: ``add`` of one, or replacing one, is ``E_FORBIDDEN``
+(protocol 1.3). The user adds it locally (``sonara engines add <id> --kind
+command``, or ``engines.json``); ``reload`` makes a running runtime read
+``engines.json`` again. Listing, testing, selecting and removing one work.
+"""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+Send = Callable[[str, dict], dict]
+
+#: The values of a profile's ``send_mode`` (#235).
+SEND_MODES = ("message", "sentence")
+
+
+class Engines:
+    """``engine_list``, ``engine_add``, ``engine_remove``, ``engine_key``,
+    ``engine_test``, ``engine_reload``, ``engine_models`` and ``voices`` with
+    ``refresh``."""
+
+    def __init__(self, send: Send):
+        self._send = send
+
+    def list(self) -> dict:
+        """``engine_list``: the profiles, the built-in engines, kinds and presets."""
+        return self._send("engine_list", {})
+
+    def add(self, profile: dict, secret: Optional[str] = None, replace: bool = False) -> dict:
+        """``engine_add``. It does not select the engine: ``set engine`` does."""
+        fields: dict = {"engine": profile}
+        if secret is not None:
+            fields["secret"] = secret
+        if replace:
+            fields["replace"] = True
+        return self._send("engine_add", fields)
+
+    def reload(self) -> dict:
+        """``engine_reload`` (protocol 1.3): the runtime reads ``engines.json``
+        again. It takes no profile. Replies like ``list``, plus ``problems``."""
+        return self._send("engine_reload", {})
+
+    def remove(self, engine: str, forget_key: bool = True) -> dict:
+        """``engine_remove``; the stored key goes too unless ``forget_key`` is false."""
+        fields: dict = {"engine": engine}
+        if not forget_key:
+            fields["forget_key"] = False
+        return self._send("engine_remove", fields)
+
+    def set_key(self, engine: str, secret: Optional[str]) -> dict:
+        """``engine_key``: store a key, or delete it with ``None``."""
+        return self._send("engine_key", {"engine": engine, "secret": secret})
+
+    def test(self, engine: str, text: Optional[str] = None, voice: Optional[str] = None,
+             play: bool = True) -> dict:
+        """``engine_test``: one synthesis with no fallback, at the current rate."""
+        fields: dict = {"engine": engine}
+        if text is not None:
+            fields["text"] = text
+        if voice is not None:
+            fields["voice"] = voice
+        if not play:
+            fields["play"] = False
+        return self._send("engine_test", fields)
+
+    def models(self, engine: Optional[str] = None, refresh: bool = False,
+               profile: Optional[dict] = None, secret: Optional[str] = None) -> dict:
+        """``engine_models`` (protocol 1.5): the provider's models now, of a
+        saved ``engine`` (``refresh`` asks the provider again) or of a draft
+        ``profile`` (with ``secret`` for this request only). Replies
+        ``{models: [{id, name}], list, takes_model, required, error?}``."""
+        if profile is not None:
+            fields: dict = {"profile": profile}
+            if secret is not None:
+                fields["secret"] = secret
+            return self._send("engine_models", fields)
+        if engine is None:
+            raise ValueError("models needs an engine or a profile")
+        fields = {"engine": engine}
+        if refresh:
+            fields["refresh"] = True
+        return self._send("engine_models", fields)
+
+    def voices(self, engine: str, refresh: bool = False) -> list:
+        """``voices`` of one engine; ``refresh`` asks the provider again."""
+        fields: dict = {"engine": engine}
+        if refresh:
+            fields["refresh"] = True
+        return self._send("voices", fields)["voices"]

sonara_client/errors.py

@@ -0,0 +1,23 @@
+"""Errors of the Sonara client."""
+from __future__ import annotations
+
+from typing import Optional
+
+# Client-side codes, next to the protocol's E_* codes that come from the runtime.
+E_NOT_RUNNING = "E_NOT_RUNNING"  # nothing running, nothing to start
+E_START_FAILED = "E_START_FAILED"  # the bundled runtime did not come up in time
+E_CLOSED = "E_CLOSED"  # the connection closed before the reply
+
+
+class SonaraError(Exception):
+    """A coded failure: a protocol error (``E_BUSY``, ``E_NOT_FOUND``...) or
+    one of the client's own (``E_NOT_RUNNING``, ``E_START_FAILED``,
+    ``E_CLOSED``)."""
+
+    def __init__(self, code: str, message: str, reason: Optional[str] = None):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+        #: Protocol 1.2: why an external engine failed (``auth``, ``quota``,
+        #: ``network``...), on an ``E_ENGINE`` of ``engine_test``.
+        self.reason = reason

sonara_client/extensions.py

@@ -0,0 +1,122 @@
+"""Extension namespaces (spec sections 4.2 to 4.4).
+
+Each method sends one protocol message as is; all behaviour lives in the
+runtime. A runtime that does not offer the extension (or no client enabled
+it in ``hello``) answers ``E_UNSUPPORTED``. ``extra`` keyword fields are
+sent along unchanged, for fields a later protocol minor adds.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Sequence, Union
+
+Send = Callable[[str, dict], dict]
+Turn = Union[str, int]
+
+
+def _defined(fields: dict) -> dict:
+    return {k: v for k, v in fields.items() if v is not None}
+
+
+class Channels:
+    """``channels``: named sources, each with its own queue and policy."""
+
+    def __init__(self, send: Send):
+        self._send = send
+
+    def open(self, channel: str, label: Optional[str] = None, host_tab: Optional[str] = None,
+             policy: Optional[str] = None, keep_label: Optional[bool] = None,
+             **extra: Any) -> dict:
+        """``channel_open`` (policy ``latest`` or ``queue``; ``keep_label``: an
+        open channel keeps the label it has, runtime 0.20.3)."""
+        return self._send("channel_open", _defined(
+            {**extra, "channel": channel, "label": label, "host_tab": host_tab, "policy": policy,
+             "keep_label": keep_label}))
+
+    def close(self, channel: str, **extra: Any) -> dict:
+        """``channel_close``."""
+        return self._send("channel_close", _defined({**extra, "channel": channel}))
+
+    def focus(self, channel: str, **extra: Any) -> dict:
+        """``focus``: bring a channel to the front."""
+        return self._send("focus", _defined({**extra, "channel": channel}))
+
+    def speak(self, channel: str, text: str, mode: Optional[str] = None, interrupt: Optional[bool] = None,
+              label: Optional[str] = None, **extra: Any) -> int:
+        """``speak`` on a channel; the item id."""
+        r = self._send("speak", _defined({**extra, "channel": channel, "text": text, "mode": mode,
+                                          "interrupt": interrupt, "label": label}))
+        return r["item_id"]
+
+    def control(self, channel: str, action: str, **extra: Any) -> None:
+        """``control`` scoped to a channel."""
+        self._send("control", _defined({**extra, "channel": channel, "action": action}))
+
+    def next_channel(self, **extra: Any) -> None:
+        """``control`` ``next_channel``."""
+        self._send("control", _defined({**extra, "action": "next_channel"}))
+
+    def flush(self, **extra: Any) -> dict:
+        """``control`` ``flush``: stop only the session being read (the flush hotkey, #228)."""
+        return self._send("control", _defined({**extra, "action": "flush"}))
+
+
+class Agent:
+    """``agent`` (needs ``channels``): streaming turns, decisions, earcons."""
+
+    def __init__(self, send: Send):
+        self._send = send
+
+    def stream(self, channel: str, turn: Turn, delta: str, index: int, final: bool,
+               t: Optional[float] = None, **extra: Any) -> dict:
+        """``stream``: one delta of a turn's text (``t``: sender start time)."""
+        return self._send("stream", _defined({**extra, "channel": channel, "turn": turn, "delta": delta,
+                                              "index": index, "final": final, "t": t}))
+
+    def turn_start(self, channel: str, turn: Turn, **extra: Any) -> dict:
+        """``turn_start``."""
+        return self._send("turn_start", _defined({**extra, "channel": channel, "turn": turn}))
+
+    def turn_end(self, channel: str, turn: Turn, **extra: Any) -> dict:
+        """``turn_end``."""
+        return self._send("turn_end", _defined({**extra, "channel": channel, "turn": turn}))
+
+    def ask(self, channel: str, kind: str, text: str, options: Optional[Sequence[Any]] = None,
+            **extra: Any) -> dict:
+        """``ask``: ``question``, ``permission`` or ``plan``, spoken with priority."""
+        return self._send("ask", _defined({**extra, "channel": channel, "kind": kind, "text": text,
+                                           "options": list(options) if options is not None else None}))
+
+    def earcon(self, kind: str, **extra: Any) -> dict:
+        """``earcon``."""
+        return self._send("earcon", _defined({**extra, "kind": kind}))
+
+    def set_mute_level(self, level: int) -> dict:
+        """``set mute_level`` 0, 1 or 2."""
+        return self._send("set", {"key": "mute_level", "value": level})
+
+    def set_summaries(self, value: dict) -> dict:
+        """``set summaries``."""
+        return self._send("set", {"key": "summaries", "value": value})
+
+
+class System:
+    """``system`` (Windows): other apps' audio, global hotkeys, the settings page."""
+
+    def __init__(self, send: Send):
+        self._send = send
+
+    def set_audio_mode(self, mode: str) -> dict:
+        """``set audio_mode`` (``duck``, ``pause`` or ``off``)."""
+        return self._send("set", {"key": "audio_mode", "value": mode})
+
+    def set_duck_level(self, level: int) -> dict:
+        """``set duck_level``."""
+        return self._send("set", {"key": "duck_level", "value": level})
+
+    def set_hotkeys(self, hotkeys: dict) -> dict:
+        """``set hotkeys``."""
+        return self._send("set", {"key": "hotkeys", "value": hotkeys})
+
+    def settings_url(self) -> str:
+        """``get settings_url``."""
+        return self._send("get", {"key": "settings_url"})["value"]

sonara_client/version.py

@@ -0,0 +1,5 @@
+"""Version of this package and the protocol it speaks."""
+from __future__ import annotations
+
+__version__ = "0.21.7"
+PROTOCOL = {"major": 1, "minor": 0}

sonara_client-0.21.7.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: sonara-client
+Version: 0.21.7
+Summary: Client for the Sonara text-to-speech runtime (protocol v1). Standard library only.
+Maintainer: Max Aubert
+License: MIT
+Project-URL: Homepage, https://github.com/Maxaubert/Sonara
+Project-URL: Documentation, https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sonara-client
+
+Talk to the Sonara text-to-speech runtime from Python 3.9+. Standard library only.
+
+```python
+import sonara_client
+
+with sonara_client.connect("my-app", runtime_path=r"C:\path\to\sonarad.exe") as sonara:
+    item = sonara.speak("Hello.", label="greeting")
+    sonara.set("rate", 240)
+    with sonara.subscribe(["state", "items"]) as events:
+        for e in events:
+            if e["event"] == "item" and e["item_id"] == item and e["phase"] != "started":
+                break
+```
+
+- `connect(client_name, *, runtime_path=None, home=None, autostart=True, require=(), extensions=(), keep_alive=False)`: finds the shared runtime through `runtime.json`, starts the bundled `sonarad.exe` when none is usable (`runtime_path`, default `SONARA_RUNTIME`), takes over an idle incompatible one.
+- `speak(text, mode=None, interrupt=None, label=None)` returns the item id; `control(action)`; `set(key, value)` / `get(key)`; `voices(engine=None)`.
+- `subscribe(events)` opens an event stream on its own connection: iterate it, or `read(timeout)`.
+- `channels`, `agent`, `system`: extension namespaces that send the protocol's extension messages as they are.
+- Errors are `SonaraError` with a `code`. The client is thread-safe.
+
+Guide: [Bundle Sonara in your app](https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md). Tests: `python -m pytest clients/python/tests -q` (the end-to-end ones need `cargo build -p sonarad`).
+
+MIT. Ship `THIRD_PARTY_NOTICES.md` with an app that bundles the runtime.

sonara_client-0.21.7.dist-info/RECORD

@@ -0,0 +1,14 @@
+sonara_client/__init__.py,sha256=7rGPlHXBcTpsjI4pMCm3pHeefVoZ0rlrOS6Bjo3t-dI,981
+sonara_client/client.py,sha256=K7_D1Le9IZ81cEeGWdNJX2SUlOFEXR7CPSDSxjpw_nM,5044
+sonara_client/connect.py,sha256=AxdF43OXhQWmhEcEtUGt7Qjkx5X8Xq9yQ2Jz27HknBY,6640
+sonara_client/connection.py,sha256=C7mOYbT-zsrpmN436S9I_3vKd9Gd4CBuqLltVT8BaUs,4431
+sonara_client/discovery.py,sha256=6NwlW3_v5KtPRHBM-vvNB1_Enw76oqsKlEPqiqKp0kg,5496
+sonara_client/engines.py,sha256=i9ZHpsBuISpmOTZvD1hrNkpkD-3feGULabGU6yH-EJg,5133
+sonara_client/errors.py,sha256=_8-bjcNW9ItXhWnWio4sFJUjxZBCM2dbmDam-tQsWf4,974
+sonara_client/extensions.py,sha256=mvESGvKOeuoLFXpBy81BzPNWH0wg2EckpZuD6qGqR94,5489
+sonara_client/version.py,sha256=AmDOI4GTzDNPVD_JAoKqGqBldArZ8PV4Ja9OjtHdyCA,158
+sonara_client-0.21.7.dist-info/licenses/LICENSE,sha256=Jd33EBnpxUDjmvOo4I4R6kpK8CMf_EJccRSlQDLmHF4,1089
+sonara_client-0.21.7.dist-info/METADATA,sha256=n4USDnTdKuD8CTq8pLqdXF6a5HQnGUUTEKuVmTSfl0Y,2205
+sonara_client-0.21.7.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sonara_client-0.21.7.dist-info/top_level.txt,sha256=WnnLWWDza1RBQlgqm-ODOPGO1zsQKKzdEn0MOTx2gpg,14
+sonara_client-0.21.7.dist-info/RECORD,,

sonara_client-0.21.7.dist-info/WHEEL

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

sonara_client-0.21.7.dist-info/licenses/LICENSE

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

sonara_client-0.21.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+sonara_client