vis-agent 0.3.4.dev8055__tar.gz → 0.3.4.dev8058__tar.gz

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.3.4.dev8055
+Version: 0.3.4.dev8058
 Summary: The Vis Python SDK — author extensions and control local or remote engines.
 Project-URL: Homepage, https://vis.blockether.com
 Project-URL: Documentation, https://vis.blockether.com

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/contracts/schema/gateway.json

@@ -1437,7 +1437,8 @@
       "operations": {
         "post": {
           "request": "json",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         }
       },
       "path": "/v1/speech"
@@ -1447,11 +1448,13 @@
       "operations": {
         "delete": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         },
         "get": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         }
       },
       "path": "/v1/speech/jobs/:job-id"
@@ -1461,7 +1464,8 @@
       "operations": {
         "get": {
           "request": "none",
-          "response": "binary"
+          "response": "binary",
+          "extension": "background"
         }
       },
       "path": "/v1/speech/jobs/:job-id/audio"
@@ -1481,11 +1485,13 @@
       "operations": {
         "get": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         },
         "post": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "callback"
         }
       },
       "path": "/v1/speech/model"
@@ -1495,11 +1501,13 @@
       "operations": {
         "get": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         },
         "post": {
           "request": "binary",
-          "response": "json"
+          "response": "json",
+          "extension": "callback"
         }
       },
       "path": "/v1/speech/voices"
@@ -1509,7 +1517,13 @@
       "operations": {
         "delete": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "callback"
+        },
+        "patch": {
+          "request": "json",
+          "response": "json",
+          "extension": "callback"
         }
       },
       "path": "/v1/speech/voices/:voice-id"
@@ -1519,7 +1533,8 @@
       "operations": {
         "get": {
           "request": "none",
-          "response": "binary"
+          "response": "binary",
+          "extension": "background"
         }
       },
       "path": "/v1/speech/voices/:voice-id/sample"
@@ -1601,7 +1616,8 @@
       "operations": {
         "post": {
           "request": "binary",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         }
       },
       "path": "/v1/voice"
@@ -1611,11 +1627,13 @@
       "operations": {
         "delete": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         },
         "get": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         }
       },
       "path": "/v1/voice/jobs/:job-id"
@@ -1635,11 +1653,13 @@
       "operations": {
         "get": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "background"
         },
         "post": {
           "request": "none",
-          "response": "json"
+          "response": "json",
+          "extension": "callback"
         }
       },
       "path": "/v1/voice/model"

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.3.4.dev8055"
+version = "0.3.4.dev8058"
 description = "The Vis Python SDK — author extensions and control local or remote engines."
 readme = "README.md"
 requires-python = ">=3.12"

vis_agent-0.3.4.dev8058/release-tag

@@ -0,0 +1 @@
+beta-e21d3544abdc993020fd27956ece8df3a4736c1e

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/src/blockether/vis/engine/__init__.py

@@ -36,6 +36,7 @@ from ._council import (
 from ._install import InstallError, ensure_installed, install
 from ._local import LocalEngine
 from ._models import Model, SessionModel
+from ._speech import Speech, SpeechAudio, Transcript, Voice
 
 __all__ = [
     "Agent",
@@ -65,10 +66,14 @@ __all__ = [
     "Response",
     "Session",
     "SessionModel",
+    "Speech",
+    "SpeechAudio",
     "StructuredOutputError",
+    "Transcript",
     "TransportError",
     "Turn",
     "VisTimeout",
+    "Voice",
     "ensure_installed",
     "final_answer",
     "install",

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/src/blockether/vis/engine/_client.py

@@ -29,6 +29,7 @@ from blockether.vis.views import InputView, LiveView, ViewEvent
 
 if TYPE_CHECKING:
     from ._agent import ResponseModel
+    from ._speech import Speech
 
 JSONValue: TypeAlias = (
     str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
@@ -401,6 +402,13 @@ class ExecutionLayer(ABC):
         except OSError:
             raise TransportError("gateway response interrupted") from None
 
+    @property
+    def speech(self) -> Speech:
+        """Return the `Speech` API: voices, synthesis and transcription."""
+        from ._speech import Speech
+
+        return Speech(self)
+
     def session(self, sid: str) -> Session:
         """Return a lightweight handle for an existing session ID.
 
@@ -2857,6 +2865,25 @@ class ExecutionLayer(ABC):
         )
         return response.json()
 
+    def patch_speech_voice(
+        self,
+        voice_id: str,
+        *,
+        query: Query | None = None,
+        timeout: float | None = None,
+        body: JSONValue = None,
+    ) -> JSONValue:
+        """PATCH /v1/speech/voices/:voice-id — json response."""
+        response = self._request(
+            "PATCH",
+            "/v1/speech/voices/:voice-id",
+            path={"voice-id": voice_id},
+            query=query,
+            timeout=timeout,
+            body=body,
+        )
+        return response.json()
+
     def get_speech_voice_sample(
         self, voice_id: str, *, query: Query | None = None, timeout: float | None = None
     ) -> Response:

vis_agent-0.3.4.dev8058/src/blockether/vis/engine/_speech.py

@@ -0,0 +1,289 @@
+"""Speech API: voices, synthesis and transcription through the gateway engines.
+
+Use `ExecutionLayer.speech` from the SDK, or `vis.speech` inside an extension.
+Both send the same canonical gateway requests.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ._client import GatewayError, ProtocolError, VisTimeout
+
+if TYPE_CHECKING:
+    from ._client import ExecutionLayer
+
+CLONING_ENGINE = "pocket-tts-local"
+"""The engine that learns a voice from a recording."""
+
+_UNSET: Any = object()
+_POLL_SECONDS = 0.25
+
+
+@dataclass(frozen=True, slots=True)
+class Voice:
+    """One voice that a speaking engine can use."""
+
+    id: str
+    label: str
+    engine: str
+    language: str | None = None
+    is_imported: bool = False
+    clip_text: str | None = None
+    license: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SpeechAudio:
+    """Audio that an engine spoke, as the bytes of one file."""
+
+    content: bytes
+    media_type: str
+    engine: str | None
+    voice: str | None
+    seed: int | None
+
+    def save(self, path: str | Path) -> Path:
+        """Write the audio to `path`, create missing parents and return the path."""
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(self.content)
+        return target
+
+
+@dataclass(frozen=True, slots=True)
+class Transcript:
+    """The text that a transcription engine heard in a recording."""
+
+    text: str
+    engine: str | None
+    segments: tuple[dict[str, Any], ...] = ()
+
+
+def _voice(entry: Any, engine: str) -> Voice:
+    if not isinstance(entry, dict) or not isinstance(entry.get("id"), str):
+        raise ProtocolError("invalid voice entry")
+    return Voice(
+        id=entry["id"],
+        label=str(entry.get("label") or entry["id"]),
+        engine=engine,
+        language=entry.get("language"),
+        is_imported=bool(entry.get("is_imported")),
+        clip_text=entry.get("clip_text"),
+        license=entry.get("license"),
+    )
+
+
+def _object(reply: Any, what: str) -> dict[str, Any]:
+    """The JSON object of a gateway answer, or ProtocolError for another shape."""
+    if not isinstance(reply, dict):
+        raise ProtocolError(f"invalid {what} answer")
+    return reply
+
+
+def _audio_bytes(audio: str | Path | bytes) -> bytes:
+    if isinstance(audio, bytes):
+        return audio
+    return Path(audio).expanduser().read_bytes()
+
+
+def _media_type(headers: dict[str, str]) -> str:
+    for key, value in headers.items():
+        if key.lower() == "content-type" and value:
+            return value.split(";")[0].strip()
+    return "audio/wav"
+
+
+def _engine_query(engine: str | None, **extra: str | None) -> dict[str, str] | None:
+    query = {k: v for k, v in {"engine": engine, **extra}.items() if v is not None}
+    return query or None
+
+
+class Speech:
+    """Manage voices, speak text and transcribe audio with the gateway engines.
+
+    Without `engine`, a call uses the engine that the gateway selected. Voice changes
+    use the cloning engine `pocket-tts-local` by default. Long work runs as a gateway
+    job; these methods wait for it and return the result.
+    """
+
+    def __init__(self, layer: ExecutionLayer):
+        self._layer = layer
+
+    def voices(self, engine: str | None = None) -> list[Voice]:
+        """List the voices of `engine`, imported voices included."""
+        reply = _object(
+            self._layer.get_speech_voices(query=_engine_query(engine)), "voices"
+        )
+        name = str((reply.get("engine") or {}).get("id") or engine or "")
+        return [_voice(entry, name) for entry in reply.get("voices") or []]
+
+    def add_voice(
+        self,
+        recording: str | Path | bytes,
+        name: str,
+        *,
+        language: str | None = None,
+        transcript: str | None = None,
+        engine: str = CLONING_ENGINE,
+    ) -> Voice:
+        """Import a recording of one speaker as a voice and return it.
+
+        Use 3 to 30 seconds of clean speech. WAV works everywhere; the gateway converts
+        other containers when it can. `transcript` is what the clip says and improves
+        the clone. A voice with the same id is replaced, so this also replaces the audio
+        of an existing voice. Raises `GatewayError` 400 for an unusable recording and
+        409 for an engine that cannot learn voices.
+        """
+        if not name or not name.strip():
+            raise ValueError("name must not be blank")
+        reply = _object(
+            self._layer.post_speech_voices(
+                content=_audio_bytes(recording),
+                query=_engine_query(engine, name=name, lang=language, text=transcript),
+            ),
+            "voice",
+        )
+        return _voice(reply.get("voice"), engine)
+
+    def update_voice(
+        self,
+        voice_id: str,
+        *,
+        name: str | None = _UNSET,
+        language: str | None = _UNSET,
+        transcript: str | None = _UNSET,
+        engine: str = CLONING_ENGINE,
+    ) -> Voice:
+        """Change the label, language or clip transcript of an imported voice.
+
+        An omitted argument keeps its value; `None` or "" removes it. The id stays the
+        same. Raises `GatewayError` 404 when the engine has no such imported voice.
+        """
+        body: dict[str, Any] = {
+            key: value
+            for key, value in (
+                ("name", name),
+                ("language", language),
+                ("text", transcript),
+            )
+            if value is not _UNSET
+        }
+        if not body:
+            raise ValueError("give name, language or transcript")
+        reply = _object(
+            self._layer.patch_speech_voice(
+                voice_id, body=body, query=_engine_query(engine)
+            ),
+            "voice",
+        )
+        return _voice(reply.get("voice"), engine)
+
+    def remove_voice(self, voice_id: str, *, engine: str = CLONING_ENGINE) -> bool:
+        """Delete an imported voice. Return False when the engine has no such voice."""
+        try:
+            self._layer.delete_speech_voice(voice_id, query=_engine_query(engine))
+        except GatewayError as error:
+            if error.status == 404:
+                return False
+            raise
+        return True
+
+    def voice_sample(self, voice_id: str, *, engine: str | None = None) -> bytes:
+        """Return a short audio sample of a voice. Raises `GatewayError` 404 without one."""
+        return self._layer.get_speech_voice_sample(
+            voice_id, query=_engine_query(engine)
+        ).content
+
+    def model(self, engine: str | None = None, *, prepare: bool = False) -> dict:
+        """Return the readiness of a speaking engine; `prepare=True` starts its download."""
+        query = _engine_query(engine)
+        if prepare:
+            return _object(self._layer.post_speech_model(query=query), "model")
+        return _object(self._layer.get_speech_model(query=query), "model")
+
+    def speak(
+        self,
+        text: str,
+        *,
+        voice: str | None = None,
+        engine: str | None = None,
+        seed: int | None = None,
+        timeout: float = 600,
+    ) -> SpeechAudio:
+        """Speak `text` and return the audio, usually 24 kHz mono WAV.
+
+        `seed` selects another take of the same text on engines that sample noise,
+        such as `vibevoice-local`. The gateway speaks at most 20000 characters at once.
+        Raises `GatewayError` 425 while the engine model is not ready and `VisTimeout`
+        when the job takes longer than `timeout` seconds.
+        """
+        if not text or not text.strip():
+            raise ValueError("text must not be blank")
+        if seed is not None and not (type(seed) is int and 0 <= seed <= 2147483647):
+            raise ValueError("seed must be an integer from 0 to 2147483647")
+        body: dict[str, Any] = {"text": text}
+        if voice is not None:
+            body["voice"] = voice
+        if seed is not None:
+            body["seed"] = seed
+        response = self._layer._request(
+            "POST", "/v1/speech", body=body, query=_engine_query(engine)
+        )
+        if response.status == 200:
+            return SpeechAudio(
+                response.content, _media_type(response.headers), engine, voice, seed
+            )
+        job = self._wait("speech", response.json(), timeout)
+        audio = self._layer.get_speech_job_audio(job["id"])
+        return SpeechAudio(
+            audio.content,
+            _media_type(audio.headers),
+            job.get("engine") or engine,
+            voice,
+            seed,
+        )
+
+    def transcribe(
+        self,
+        audio: str | Path | bytes,
+        *,
+        engine: str | None = None,
+        timeout: float = 600,
+    ) -> Transcript:
+        """Transcribe a 16-bit PCM WAV recording and return its text.
+
+        Engines include `parakeet-local` and `vibevoice-asr-local`. Raises `GatewayError`
+        400 for audio that is not WAV and `VisTimeout` after `timeout` seconds.
+        """
+        job = self._layer.post_voice(
+            content=_audio_bytes(audio), query=_engine_query(engine)
+        )
+        job = self._wait("voice", job, timeout)
+        segments = job.get("segments") or ()
+        return Transcript(
+            str(job.get("text") or ""),
+            job.get("engine") or engine,
+            tuple(s for s in segments if isinstance(s, dict)),
+        )
+
+    def _wait(self, direction: str, job: Any, timeout: float) -> dict:
+        if not isinstance(job, dict) or not isinstance(job.get("id"), str):
+            raise ProtocolError(f"invalid {direction} job")
+        get = (
+            self._layer.get_speech_job
+            if direction == "speech"
+            else self._layer.get_voice_job
+        )
+        deadline = time.monotonic() + timeout
+        while not job.get("is_done"):
+            if time.monotonic() > deadline:
+                raise VisTimeout(f"{direction} job {job['id']} is still running")
+            time.sleep(_POLL_SECONDS)
+            job = get(job["id"])
+        if job.get("phase") == "failed":
+            raise RuntimeError(str(job.get("error") or f"{direction} job failed"))
+        return job

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/src/blockether/vis/evals/compare.py

@@ -122,18 +122,19 @@ def _crossed_caveat(base: tuple[str, ...], other: tuple[str, ...]) -> str:
 def _margin_caveat(
     verdict: str, interval: tuple[float, float], margin: float | None
 ) -> str | None:
-    if not margin or verdict not in ("better", "worse"):
+    if margin is None or verdict not in ("better", "worse"):
         return None
     low, high = interval if verdict == "better" else (-interval[1], -interval[0])
     change = "gain" if verdict == "better" else "loss"
     if high < margin:
         return (
-            f"The {change} is real, but smaller than the margin of {margin:g} points."
+            f"The {change} is real, but smaller than the margin of {margin:.12g} "
+            "points."
         )
     if low < margin:
         return (
             f"The {change} is real, but it can be smaller than the margin of "
-            f"{margin:g} points."
+            f"{margin:.12g} points."
         )
     return None
 
@@ -144,7 +145,7 @@ def _verdict(interval: tuple[float, float], margin: float | None) -> str:
         return "better"
     if high < 0:
         return "worse"
-    if not margin:
+    if margin is None:
         return "no measurable difference"
     if -margin < low and high < margin:
         return "equivalent"

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/src/blockether/vis/extension.py

@@ -308,8 +308,14 @@ def __getattr__(name: str) -> Any:
     """Create the API of the bound session through the host on first use.
 
     `session` is the `Session` of the bound Vis session, and `council` is its
-    `Council`. Without a bound session, both raise `RuntimeError`.
+    `Council`. Without a bound session, both raise `RuntimeError`. `speech` is the
+    `blockether.vis.engine.Speech` API of the gateway: voices, synthesis and
+    transcription. A voice change needs an extension callback.
     """
+    if name == "speech":
+        from blockether.vis.engine._speech import Speech
+
+        return Speech(_host_layer())
     if name in ("session", "council"):
         sid = _host.bound_session()
         if not sid:

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/tests/test_api_guides.py

@@ -93,7 +93,7 @@ _CONCEPTS = sorted(
 
 def test_pages_name_gateway_routes_only_on_http_pages():
     # An empty topic list once turned the parametrized cases below into zero cases.
-    assert len(_CONCEPTS) == 8, f"merged API pages found: {_CONCEPTS}"
+    assert len(_CONCEPTS) == 9, f"merged API pages found: {_CONCEPTS}"
     for page in _PAGES:
         if page.name == "http-api.md":
             continue

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/tests/test_contracts.py

@@ -56,10 +56,10 @@ def test_gateway_routes_and_lease_policy_are_shared():
     assert 0 < lease["touch_ms"] < lease["keepalive_ms"] < lease["ttl_ms"]
     assert 0 < lease["keepalive_timeout_ms"] < lease["keepalive_ms"]
     assert len(routes) == 169
-    assert len(operations) == 205
+    assert len(operations) == 206
     assert Counter(operation["request"] for operation in operations) == {
         "none": 123,
-        "json": 76,
+        "json": 77,
         "binary": 6,
     }
     assert by_path["/v1/decisions/models"]["operations"]["get"] == {
@@ -93,6 +93,12 @@ def test_gateway_routes_and_lease_policy_are_shared():
     assert by_path["/v1/speech/voices"]["operations"]["post"] == {
         "request": "binary",
         "response": "json",
+        "extension": "callback",
+    }
+    assert by_path["/v1/speech/voices/:voice-id"]["operations"]["patch"] == {
+        "request": "json",
+        "response": "json",
+        "extension": "callback",
     }
     assert by_path["/v1/settings"]["operations"]["patch"] == {
         "request": "json",

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/tests/test_evals_compare.py

@@ -4,6 +4,7 @@ The calibration tests run seeded simulations. They prove the claims of the
 evaluation guide on false verdicts and power.
 """
 
+import math
 import random
 
 import pytest
@@ -161,17 +162,37 @@ def _simulate(rng, tasks, change, margin=None, runs=1):
     return compare_cases(side(0.0), side(change), margin_points=margin)
 
 
-@pytest.mark.parametrize(
-    ("tasks", "runs"), [(12, 1), (16, 1), (30, 1), (30, 3), (80, 1)]
-)
-def test_without_a_change_a_verdict_is_rare(tasks, runs):
-    rng = random.Random(tasks * runs)
+def _verdict_chance(tasks, chance):
+    # The exact chance of a verdict without a true change. Each case becomes better or
+    # worse with `chance`, so the changed cases follow a trinomial distribution.
+    total = 0.0
+    for up in range(tasks + 1):
+        for down in range(tasks - up + 1):
+            same = tasks - up - down
+            changes = [1] * up + [-1] * down + [0] * same
+            if compare_cases(*_changes(changes)).verdict != "no measurable difference":
+                ways = math.factorial(tasks) // (
+                    math.factorial(up) * math.factorial(down) * math.factorial(same)
+                )
+                total += ways * chance ** (up + down) * (1 - 2 * chance) ** same
+    return total
+
+
+@pytest.mark.parametrize("tasks", [12, 16, 20, 30, 80])
+def test_without_a_change_a_verdict_is_rare(tasks):
+    # Pass rates from 30% to 70%: a case changes in each direction with chance
+    # E[p(1 - p)] = 0.25 - 0.4**2 / 12.
+    assert 0.05 <= _verdict_chance(tasks, 0.25 - 0.4**2 / 12) <= 0.07
+
+
+def test_without_a_change_a_verdict_is_rarer_with_repeats():
+    rng = random.Random(90)
     trials = 1000
     verdicts = sum(
-        _simulate(rng, tasks, 0.0, runs=runs).verdict != "no measurable difference"
+        _simulate(rng, 30, 0.0, runs=3).verdict != "no measurable difference"
         for _ in range(trials)
     )
-    assert verdicts / trials <= 0.06
+    assert verdicts / trials <= 0.04
 
 
 def test_the_detectable_change_shows_with_80_percent_power():

{vis_agent-0.3.4.dev8055 → vis_agent-0.3.4.dev8058}/tests/test_evals_stats.py

@@ -211,15 +211,14 @@ def _wilson_coverage(runs, rate):
 def test_wilson_interval_covers_the_true_rate_95_percent_of_the_time(runs):
     coverages = [_wilson_coverage(runs, percent / 100) for percent in range(5, 96, 5)]
     assert 0.94 <= sum(coverages) / len(coverages) <= 0.96
-    assert min(coverages) >= 0.91
+    dense = [_wilson_coverage(runs, permille / 1000) for permille in range(50, 951)]
+    assert min(dense) >= 0.89
 
 
 @pytest.mark.parametrize("runs", [10, 30, 100])
 def test_wilson_interval_covers_less_near_zero(runs):
-    coverages = [
-        _wilson_coverage(runs, permille / 1000) for permille in range(5, 50, 5)
-    ]
-    assert 0.85 <= min(coverages) < 0.92
+    coverages = [_wilson_coverage(runs, rate / 10000) for rate in range(10, 500)]
+    assert 0.83 <= min(coverages) < 0.85
 
 
 def test_mcnemar_exact_keeps_false_alarms_at_most_5_percent():