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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.3.4.dev8048
+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.dev8048 → vis_agent-0.3.4.dev8058}/contracts/schema/evals.json

@@ -149,6 +149,12 @@
         },
         "candidate_name": {
           "type": "string"
+        },
+        "margin_points": {
+          "description": "The smallest change in points that matters. It splits a result without a clear change into equivalent, not worse, not better or inconclusive.",
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "maximum": 100
         }
       },
       "required": [
@@ -649,7 +655,16 @@
           "maxItems": 2
         },
         "verdict": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "better",
+            "worse",
+            "no measurable difference",
+            "equivalent",
+            "not worse",
+            "not better",
+            "inconclusive"
+          ]
         },
         "detectable_change_points": {
           "type": "number"
@@ -683,6 +698,12 @@
           "items": {
             "type": "string"
           }
+        },
+        "margin_points": {
+          "type": [
+            "number",
+            "null"
+          ]
         }
       },
       "required": [
@@ -698,7 +719,8 @@
         "worse",
         "better",
         "unpaired",
-        "caveats"
+        "caveats",
+        "margin_points"
       ],
       "additionalProperties": false
     },

{vis_agent-0.3.4.dev8048 → 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.dev8048 → vis_agent-0.3.4.dev8058}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.3.4.dev8048"
+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.dev8048 → 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.dev8048 → 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.dev8048 → vis_agent-0.3.4.dev8058}/src/blockether/vis/evals/_gateway.py

@@ -68,6 +68,15 @@ def _required_text(body: Mapping, key: str) -> str:
     return value
 
 
+def _number(body: Mapping, key: str) -> float | None:
+    value = body.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"`{key}` must be a number.")
+    return float(value)
+
+
 def _cases(body: Mapping, key: str) -> dict[tuple[str, ...], tuple[int, int]]:
     rows = body.get(key)
     if not isinstance(rows, list):
@@ -114,6 +123,7 @@ def _compare(body: Mapping):
         _cases(body, "candidate"),
         baseline_name=_word(body, "baseline_name", "baseline"),
         candidate_name=_word(body, "candidate_name", "candidate"),
+        margin_points=_number(body, "margin_points"),
     )