vocalstack 1.0.0a1__tar.gz → 1.0.0a3__tar.gz

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalstack
-Version: 1.0.0a1
+Version: 1.0.0a3
 Summary: VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming.
 Project-URL: Homepage, https://vocalstack.com
 License-Expression: MIT
@@ -18,6 +18,8 @@ The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
 are pydantic models generated from the API's one OpenAPI document
 (`/v1/openapi.json`), with snake_case attributes.
 
+Read more about the [VocalStack Python SDK](https://vocalstack.com/#developers) and our other SDKs on the [VocalStack website](https://vocalstack.com/).
+
 ```python
 import asyncio, os
 from vocalstack import VocalStack
@@ -45,7 +47,8 @@ pip install vocalstack
 
 - [Quickstart](https://github.com/vocalstack/python-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
 - [Transcribe a file](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
-- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL, a YouTube video or a recording on a video or audio site, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Search your transcriptions](https://github.com/vocalstack/python-sdk/blob/main/docs/search-transcriptions.md): Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.
 - [Stream a microphone](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
 - [Stream a file at full speed](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
 - [Go live](https://github.com/vocalstack/python-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/README.md

@@ -5,6 +5,8 @@ The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
 are pydantic models generated from the API's one OpenAPI document
 (`/v1/openapi.json`), with snake_case attributes.
 
+Read more about the [VocalStack Python SDK](https://vocalstack.com/#developers) and our other SDKs on the [VocalStack website](https://vocalstack.com/).
+
 ```python
 import asyncio, os
 from vocalstack import VocalStack
@@ -32,7 +34,8 @@ pip install vocalstack
 
 - [Quickstart](https://github.com/vocalstack/python-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
 - [Transcribe a file](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
-- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a link](https://github.com/vocalstack/python-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL, a YouTube video or a recording on a video or audio site, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Search your transcriptions](https://github.com/vocalstack/python-sdk/blob/main/docs/search-transcriptions.md): Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.
 - [Stream a microphone](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
 - [Stream a file at full speed](https://github.com/vocalstack/python-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
 - [Go live](https://github.com/vocalstack/python-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/SKILL.md

@@ -94,7 +94,9 @@ async def main(path):  # mp3, wav, flac, ogg, m4a, mp4 ...
     async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
         tx = await vs.transcriptions.create(
             file=path,  # a path, bytes, or an open binary file
-            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" | "on" | "off"
+            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" (default) | "on" | "off"
+            # Off unless asked for: settings summary, title, summaryTranslations,
+            # voice (spoken translations), and share_link=True (a public share link).
         )
         job = await vs.jobs.wait(tx.job.recording_id)
         if job.state != "done":
@@ -180,6 +182,17 @@ async def main(q):  # 2+ characters
 asyncio.run(main(sys.argv[1]))
 ```
 
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
+
+```python
+res = await vs.search.vector("how much does housing cost")
+for h in res.hits:
+    print(f"{h.similarity:.2f}", h.passage.media_start, h.passage.text)
+```
+
 ## Errors
 
 A failed call raises `vocalstack.VocalStackError` with `.code`, `.message`,

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vocalstack"
-version = "1.0.0a1"
+version = "1.0.0a3"
 description = "VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming."
 readme = "README.md"
 license = "MIT"
@@ -22,11 +22,8 @@ Homepage = "https://vocalstack.com"
 [tool.hatch.build.targets.wheel]
 packages = ["src/vocalstack"]
 
-# The Agent Skill ships inside the package (site-packages/vocalstack/SKILL.md)
-# so an agent can find it next to the code.
 [tool.hatch.build.targets.wheel.force-include]
 "SKILL.md" = "vocalstack/SKILL.md"
 
-# An explicit list: nothing else from the repository goes into the sdist.
 [tool.hatch.build.targets.sdist]
 only-include = ["src/vocalstack", "LICENSE", "README.md", "SKILL.md", "skills", "pyproject.toml"]

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/skills/vocalstack/SKILL.md

@@ -94,7 +94,9 @@ async def main(path):  # mp3, wav, flac, ogg, m4a, mp4 ...
     async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
         tx = await vs.transcriptions.create(
             file=path,  # a path, bytes, or an open binary file
-            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" | "on" | "off"
+            settings={"spokenLanguage": "en", "speakerLabels": "on"},  # both optional; "auto" (default) | "on" | "off"
+            # Off unless asked for: settings summary, title, summaryTranslations,
+            # voice (spoken translations), and share_link=True (a public share link).
         )
         job = await vs.jobs.wait(tx.job.recording_id)
         if job.state != "done":
@@ -180,6 +182,17 @@ async def main(q):  # 2+ characters
 asyncio.run(main(sys.argv[1]))
 ```
 
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
+
+```python
+res = await vs.search.vector("how much does housing cost")
+for h in res.hits:
+    print(f"{h.similarity:.2f}", h.passage.media_start, h.passage.text)
+```
+
 ## Errors
 
 A failed call raises `vocalstack.VocalStackError` with `.code`, `.message`,

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/src/vocalstack/__init__.py

@@ -30,7 +30,7 @@ from .errors import VocalStackError
 from .realtime import RealtimeTranscript
 from .realtime import RealtimeSession, pace_realtime
 
-__version__ = "1.0.0a1"
+__version__ = "1.0.0a3"
 
 __all__ = [
     "DEFAULT_BASE_URL",

{vocalstack-1.0.0a1 → vocalstack-1.0.0a3}/src/vocalstack/_http.py

@@ -8,7 +8,7 @@ from typing import Any, Callable, Dict, Mapping, Optional, Union
 
 import httpx
 
-from .errors import from_envelope, from_oauth
+from .errors import VocalStackError, from_envelope, from_oauth
 
 DEFAULT_BASE_URL = "https://api.vocalstack.com"
 
@@ -30,7 +30,6 @@ def listener_query(listener_token: Optional[str], share_code: Optional[str]) ->
     return {"listenerToken": listener_token, "shareCode": share_code}
 
 
-#: The wait before retrying ``503 unavailable`` when it names none.
 UNAVAILABLE_WAIT_S = 2.0
 
 
@@ -120,16 +119,19 @@ class Transport:
             h["idempotency-key"] = idempotency_key
         attempt = 0
         while True:
-            resp = await self.http.request(
-                method,
-                self.url(path),
-                params=_clean(query),
-                json=json_body,
-                files=files,
-                data=data,
-                headers=h,
-                follow_redirects=False,
-            )
+            try:
+                resp = await self.http.request(
+                    method,
+                    self.url(path),
+                    params=_clean(query),
+                    json=json_body,
+                    files=files,
+                    data=data,
+                    headers=h,
+                    follow_redirects=False,
+                )
+            except httpx.TransportError as e:
+                raise VocalStackError("unavailable", "could not reach the VocalStack API", retryable=True) from e
             if resp.status_code < 400:
                 return resp
             body = None
@@ -152,7 +154,12 @@ class Transport:
         resp = await self.raw(method, path, **kw)
         if 300 <= resp.status_code < 400:
             return {"location": resp.headers.get("location")}
-        return resp.json() if resp.content else None
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except (json.JSONDecodeError, ValueError) as e:
+            raise VocalStackError("internal", "the API answered with a body that is not JSON", status=resp.status_code, headers=resp.headers) from e
 
     async def aclose(self) -> None:
         if self.own_http: