vocalstack 1.0.0a0__tar.gz

vocalstack-1.0.0a0/.gitignore

@@ -0,0 +1,9 @@
+# Packaging: hatchling copies the nearest .gitignore into the sdist, so this
+# one stands in for the monorepo root's.
+.venv/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.env
+.env.*

vocalstack-1.0.0a0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: vocalstack
+Version: 1.0.0a0
+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: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: websockets>=13
+Description-Content-Type: text/markdown
+
+# vocalstack
+
+The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
+`VocalStack`, with one group per resource. Requests go through `httpx`; answers
+are pydantic models generated from the API's one OpenAPI document
+(`/v1/openapi.json`), with snake_case attributes.
+
+```python
+import asyncio, os
+from vocalstack import VocalStack
+
+async def main():
+    async with VocalStack(api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:  # base_url defaults to https://api.vocalstack.com
+        tx = await vs.transcriptions.create(url="https://example.com/talk.mp3")  # or file="talk.mp3"
+        job = await vs.jobs.wait(tx.job.recording_id)                 # done | failed | cropping
+        snap = await vs.recordings.transcript(job.recording_id)
+        print(" ".join(s.text for s in snap.sentences))
+        open("talk.srt", "wb").write(await vs.recordings.export(job.recording_id, "srt"))
+
+asyncio.run(main())
+```
+
+<!-- sdk-docs: generated by `make sdk-docs` from the guides; edit those, not this -->
+
+## Install
+
+Not on PyPI yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+
+## Guides
+
+- [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.
+- [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.
+- [Listen](https://github.com/vocalstack/python-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
+- [Live translation and spoken translations](https://github.com/vocalstack/python-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Errors, retries and limits](https://github.com/vocalstack/python-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
+
+<!-- /sdk-docs -->
+
+## What is what
+
+| Name | What it is | Group |
+|---|---|---|
+| realtime session | a signed token plus one socket; nothing stored | `vs.realtime` |
+| broadcast | the link listeners open | `vs.broadcasts` |
+| transcription | a file, link, microphone or stream, transcribed and stored | `vs.transcriptions` |
+| recording | one take inside a broadcast or a transcription | `vs.recordings` |
+| job | a file or link recording's transcription work | `vs.jobs` |
+
+The other groups: `vs.corrections`, `vs.share_links`, `vs.voices`,
+`vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
+Method names are the document's `operationId`s in snake_case
+(`broadcasts.start_recording` is `POST /v1/broadcasts/{id}/recordings`).
+Request fields are keyword arguments, in snake_case or the wire's camelCase
+(`settings={"spokenLanguage": "en"}`); lists return lists; binary answers
+(`recordings.export`, `recordings.clip`, `voices.sample`, ...) return bytes.
+
+```python
+VocalStack(
+    base_url=None,          # default https://api.vocalstack.com
+    api_key=None,           # an API key (vs_key_...), for a server
+    token=None,             # or: an access token / browser token, or a callable returning one
+    acting_principal=None,  # act for an organization (X-Acting-Principal)
+    device_id=None,
+    max_retries=2,          # 429s, and 503 unavailable on safe calls, retried after Retry-After
+    timeout=300.0,
+    ready_deadline_s=30.0,  # how long a socket may take to report ready
+)
+```
+
+## Realtime sessions and live recordings
+
+```python
+async with VocalStack(api_key=key) as vs:
+    # Nothing stored: a file through one socket.
+    result = await vs.realtime.transcribe_file("meeting.mp3", spoken_language="en")
+    print(result.text)
+
+    # A stored live transcription: start a recording, stream raw PCM
+    # (f32le, 16 kHz, mono) into the publisher socket.
+    tx = await vs.transcriptions.create_live(name="Standup")
+    grant = await vs.transcriptions.start_recording(tx.id)
+    async with await vs.recordings.publish(grant) as stream:
+        asyncio.create_task(pace_realtime(stream, pcm))  # then eof()
+        async for event in stream:
+            if event.type == "transcript.committed":
+                print(event.segment.speaker, event.segment.text)
+```
+
+- `transcript.draft` frames **fully replace** the live tail; never append them.
+- `transcript.committed` segments are immutable, gapless by `segment.seq`,
+  and carry word timings.
+- A dropped connection ends the socket (no resume): start a new one.
+
+## Errors
+
+`VocalStackError` carries `code` (the contract's closed enum), `message`,
+`status`, `retryable`, `details` (quota numbers, code suggestions), `headers`
+and `retry_after`.
+
+Verified against the language-agnostic conformance suite (`make conformance`)
+and against a running API (`make sdk-e2e`). For agents: `SKILL.md`.

vocalstack-1.0.0a0/README.md

@@ -0,0 +1,105 @@
+# vocalstack
+
+The VocalStack speech API for Python (3.10 or newer, asyncio): one client,
+`VocalStack`, with one group per resource. Requests go through `httpx`; answers
+are pydantic models generated from the API's one OpenAPI document
+(`/v1/openapi.json`), with snake_case attributes.
+
+```python
+import asyncio, os
+from vocalstack import VocalStack
+
+async def main():
+    async with VocalStack(api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:  # base_url defaults to https://api.vocalstack.com
+        tx = await vs.transcriptions.create(url="https://example.com/talk.mp3")  # or file="talk.mp3"
+        job = await vs.jobs.wait(tx.job.recording_id)                 # done | failed | cropping
+        snap = await vs.recordings.transcript(job.recording_id)
+        print(" ".join(s.text for s in snap.sentences))
+        open("talk.srt", "wb").write(await vs.recordings.export(job.recording_id, "srt"))
+
+asyncio.run(main())
+```
+
+<!-- sdk-docs: generated by `make sdk-docs` from the guides; edit those, not this -->
+
+## Install
+
+Not on PyPI yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+
+## Guides
+
+- [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.
+- [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.
+- [Listen](https://github.com/vocalstack/python-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
+- [Live translation and spoken translations](https://github.com/vocalstack/python-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Errors, retries and limits](https://github.com/vocalstack/python-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
+
+<!-- /sdk-docs -->
+
+## What is what
+
+| Name | What it is | Group |
+|---|---|---|
+| realtime session | a signed token plus one socket; nothing stored | `vs.realtime` |
+| broadcast | the link listeners open | `vs.broadcasts` |
+| transcription | a file, link, microphone or stream, transcribed and stored | `vs.transcriptions` |
+| recording | one take inside a broadcast or a transcription | `vs.recordings` |
+| job | a file or link recording's transcription work | `vs.jobs` |
+
+The other groups: `vs.corrections`, `vs.share_links`, `vs.voices`,
+`vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
+Method names are the document's `operationId`s in snake_case
+(`broadcasts.start_recording` is `POST /v1/broadcasts/{id}/recordings`).
+Request fields are keyword arguments, in snake_case or the wire's camelCase
+(`settings={"spokenLanguage": "en"}`); lists return lists; binary answers
+(`recordings.export`, `recordings.clip`, `voices.sample`, ...) return bytes.
+
+```python
+VocalStack(
+    base_url=None,          # default https://api.vocalstack.com
+    api_key=None,           # an API key (vs_key_...), for a server
+    token=None,             # or: an access token / browser token, or a callable returning one
+    acting_principal=None,  # act for an organization (X-Acting-Principal)
+    device_id=None,
+    max_retries=2,          # 429s, and 503 unavailable on safe calls, retried after Retry-After
+    timeout=300.0,
+    ready_deadline_s=30.0,  # how long a socket may take to report ready
+)
+```
+
+## Realtime sessions and live recordings
+
+```python
+async with VocalStack(api_key=key) as vs:
+    # Nothing stored: a file through one socket.
+    result = await vs.realtime.transcribe_file("meeting.mp3", spoken_language="en")
+    print(result.text)
+
+    # A stored live transcription: start a recording, stream raw PCM
+    # (f32le, 16 kHz, mono) into the publisher socket.
+    tx = await vs.transcriptions.create_live(name="Standup")
+    grant = await vs.transcriptions.start_recording(tx.id)
+    async with await vs.recordings.publish(grant) as stream:
+        asyncio.create_task(pace_realtime(stream, pcm))  # then eof()
+        async for event in stream:
+            if event.type == "transcript.committed":
+                print(event.segment.speaker, event.segment.text)
+```
+
+- `transcript.draft` frames **fully replace** the live tail; never append them.
+- `transcript.committed` segments are immutable, gapless by `segment.seq`,
+  and carry word timings.
+- A dropped connection ends the socket (no resume): start a new one.
+
+## Errors
+
+`VocalStackError` carries `code` (the contract's closed enum), `message`,
+`status`, `retryable`, `details` (quota numbers, code suggestions), `headers`
+and `retry_after`.
+
+Verified against the language-agnostic conformance suite (`make conformance`)
+and against a running API (`make sdk-e2e`). For agents: `SKILL.md`.

vocalstack-1.0.0a0/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: vocalstack
+description: Use when writing Python code that calls the VocalStack speech API with the vocalstack package, for example to transcribe an audio or video URL or a local file, stream live audio for realtime transcription, fetch or export a transcript (JSON, SRT, XLSX, PDF), or search transcripts. Covers installing, API keys, base URLs, five copy-paste programs and error handling (401, 402, 403, 429).
+---
+
+# VocalStack Python SDK
+
+The VocalStack API transcribes speech (files, links, live audio), with speaker
+labels and translation. The `vocalstack` package has one asyncio client,
+`VocalStack`, with one group per resource: `vs.transcriptions`, `vs.jobs`,
+`vs.recordings`, `vs.broadcasts`, `vs.search`, `vs.realtime` and a few more
+(listed at the end). Answers are pydantic models with snake_case attributes.
+
+## What is what
+
+- A **transcription** is a file, a link, a microphone or a stream, transcribed
+  and stored. Create one with `await vs.transcriptions.create(...)`.
+- A **recording** is one take inside it. Its id (`recording_id`) is what you
+  read the transcript and exports with: `await vs.recordings.transcript(recording_id)`.
+- A **job** is a file or link recording's transcription work:
+  `await vs.jobs.wait(recording_id)` polls it until it is `done` or `failed`
+  (`on_progress=lambda job: ...` sees each read: `job.state`, `job.progress.pct`).
+- A **broadcast** is a link listeners open to follow a live recording.
+- A **realtime session** (`vs.realtime`) is a socket you stream audio into and
+  read the transcript from. Nothing is stored. "Session" means only this.
+
+## Install
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate   # system Pythons refuse a bare pip install
+pip install vocalstack                           # Python 3.10 or newer
+```
+
+Before the package is published, any account installs
+the private build its environment serves: the API reference's Install section
+(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
+give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
+Or install it from a local checkout of the repository:
+
+```sh
+pip install -e /absolute/path/to/transcribe/sdks/python
+```
+
+Live transcription (program 4) also needs `ffmpeg` on PATH.
+
+Speaker numbers start at 0. A speaker of `-1` means speaker labels were off
+for that transcription, so print the text without a speaker.
+
+## Auth and base URL
+
+- Read the key from `VOCALSTACK_API_KEY` and pass it as `api_key`. It goes
+  out as `Authorization: Bearer <key>`, also on sockets.
+- An API key starts with `vs_key_`. There is one kind of key: every call is
+  real usage on the account's tier and quotas.
+- Keys are for servers. Never put a key in browser code or in a URL. The API
+  refuses a key sent from a web page (`Origin` header) or in a query string.
+- Scopes: `read` (read transcripts, search, export), `write` and
+  `recordings:publish` (create transcriptions, stream live audio), or `*`.
+- Base URL: `https://api.vocalstack.com` (the default). Override it with
+  `VOCALSTACK_BASE_URL`: `http://127.0.0.1:8090` for a local server,
+  `https://api.e2e.vocalstack.com` for e2e.
+
+Every program below opens the client the same way, inside `async def main()`
+run with `asyncio.run(main())` (a `None` base URL means the default):
+
+```python
+async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+    ...
+```
+
+## 1. Transcribe a URL and wait for the result
+
+The server fetches the link itself, so it must be a public http(s) address.
+Private, loopback and cloud-metadata addresses are refused.
+
+```python
+import asyncio, os
+from vocalstack import VocalStack
+
+async def main():
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        tx = await vs.transcriptions.create(
+            url="https://raw.githubusercontent.com/openai/whisper/main/tests/jfk.flac",
+            name="JFK sample",
+        )
+        rec = tx.job.recording_id
+        job = await vs.jobs.wait(rec)  # queued -> fetching -> transcribing -> done | failed
+        if job.state != "done":
+            raise SystemExit(f"transcription {job.state}: {job.error}")
+        snap = await vs.recordings.transcript(rec)
+        for s in snap.sentences:
+            print(f"[speaker {s.speaker}] {s.text}" if s.speaker >= 0 else s.text)
+        print("recording_id", rec)
+
+asyncio.run(main())
+```
+
+## 2. Transcribe a local file
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+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"
+        )
+        job = await vs.jobs.wait(tx.job.recording_id)
+        if job.state != "done":
+            raise SystemExit(f"transcription {job.state}: {job.error}")
+        snap = await vs.recordings.transcript(job.recording_id)
+        print(" ".join(s.text for s in snap.sentences))
+
+asyncio.run(main(sys.argv[1]))
+```
+
+## 3. Fetch a transcript or an export file
+
+The transcript holds segments (with word timings), sentences and speakers.
+Export formats are `json`, `srt`, `xlsx` and `pdf`; add `lang="<code>"` for a
+translated file. `export` returns the file's bytes.
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+async def main(rec):
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        snap = await vs.recordings.transcript(rec)
+        print(len(snap.segments), "segments,", len(snap.sentences), "sentences, state", snap.state)
+        with open("transcript.srt", "wb") as f:
+            f.write(await vs.recordings.export(rec, "srt"))
+
+asyncio.run(main(sys.argv[1]))
+```
+
+## 4. Live transcription from a microphone or a file
+
+A live transcription takes raw PCM: 32-bit float little-endian, 16 kHz, mono.
+Create it, start a recording, and open the publisher socket the grant names.
+Here ffmpeg decodes a file, and `pace_realtime` sends it at realtime speed and
+then calls `eof()`. For a microphone, read ffmpeg's stdout as it arrives
+(`-f avfoundation -i :0` on macOS, `-f pulse -i default` on Linux) and call
+`await stream.send_audio(chunk)` for each chunk.
+
+```python
+import asyncio, os, subprocess, sys
+from vocalstack import VocalStack, pace_realtime
+
+async def main(path):
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        tx = await vs.transcriptions.create_live(name="Live demo", settings={"spokenLanguage": "en"})
+        grant = await vs.transcriptions.start_recording(tx.id)
+
+        pcm = subprocess.run(["ffmpeg", "-loglevel", "error", "-i", path,
+                              "-f", "f32le", "-ac", "1", "-ar", "16000", "-"],
+                             check=True, capture_output=True).stdout
+
+        # A cold engine can take a while to load, so allow a long ready deadline.
+        async with await vs.recordings.publish(grant, ready_deadline_s=180) as stream:
+            feeder = asyncio.create_task(pace_realtime(stream, pcm))  # then eof(), which ends the recording
+            async for event in stream:
+                if event.type == "transcript.committed":
+                    print(f"[speaker {event.segment.speaker}] {event.segment.text}", flush=True)
+            await feeder
+
+        # To end a recording without eof(): vs.recordings.pause(id), then vs.recordings.stop(id).
+        snap = await vs.recordings.transcript(grant.recording.id)
+        print("final:", " ".join(s.text for s in snap.sentences))
+
+asyncio.run(main(sys.argv[1]))
+```
+
+To transcribe without storing anything, use a realtime session instead:
+`(await vs.realtime.transcribe_file("talk.mp3")).text`.
+
+## 5. Search transcripts
+
+```python
+import asyncio, os, sys
+from vocalstack import VocalStack
+
+async def main(q):  # 2+ characters
+    async with VocalStack(os.environ.get("VOCALSTACK_BASE_URL"), api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
+        res = await vs.search.query(q, limit=5)
+        for h in res.hits:
+            print(f"{h.link_name} @ {h.media_start:.1f}s [speaker {h.speaker}]: {h.text} (recording {h.recording_id})")
+
+asyncio.run(main(sys.argv[1]))
+```
+
+## Errors
+
+A failed call raises `vocalstack.VocalStackError` with `.code`, `.message`,
+`.status`, `.retryable`, `.details` (the body's `data.details`), `.headers`
+and `.retry_after` (seconds, from `Retry-After`). A `429`, and a
+`503 unavailable` on a call that is safe to repeat, is retried for you after
+its `Retry-After`, twice by default (`max_retries` on the client).
+
+| Status | `code` | What to do |
+|---|---|---|
+| 401 | `invalid_token`, `key_expired`, `key_revoked` | Check `VOCALSTACK_API_KEY`. Use the replacement key, or create a new one. |
+| 403 | `forbidden` | Usually a missing scope: the message names it, and `e.headers["www-authenticate"]` lists the scopes the route needs. A suspended key or account gets `suspended`. |
+| 402 | `insufficient_credit` | The account's credit is out. `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `await vs.billing.get()` shows the balance. |
+| 409 | `payment_method_required` | Auto top-up (`vs.billing.set_auto_top_up`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.create_checkout(kind="topup", amount=25, accept_terms=True, waive_withdrawal=True)` opens one; a signed-in person's token, never an API key). |
+| 402 | `quota_exceeded` | The plan's transcriptions-at-once limit is reached. `details`: `metric` (`concurrent_transcriptions`), `limit`, `used`, `plan`, `topUpUrl`. |
+| 429 | `rate_limited` | Retried automatically; if it still fails, wait `e.retry_after` seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
+| 503 | `unavailable` | The service is waking (its database was asleep). Retried automatically after `Retry-After` (2 s) on calls that are safe to repeat: GET, HEAD, DELETE, or any call with `idempotency_key=`. A create without a key is not retried: retry it yourself, with an `idempotency_key` so it cannot run twice. A realtime socket refused this way raises `unavailable`; a bare 503 there is `capacity_exceeded`. |
+
+```python
+from vocalstack import VocalStackError
+try:
+    await vs.search.query("country")
+except VocalStackError as e:
+    if e.code in ("insufficient_credit", "quota_exceeded"):
+        print("billing:", e.message, e.details)
+    else:
+        print(e.status, e.code, e.message)
+```
+
+## More
+
+- The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
+  `restore`, `purge`, `list_share_links`, `create_share_link`), `vs.recordings`
+  (`get`, `summarize`, `summary`, `translation`, `audio_url`, `subscribe`),
+  `vs.corrections`, `vs.share_links`, `vs.voices`, `vs.broadcasts`,
+  `vs.me` (`get`, `usage`), `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
+  Each method is its operation's name in the OpenAPI document, in snake_case
+  (`transcriptions.create` is `POST /v1/transcriptions`).
+- `<base>/llms.txt` lists every operation in a form written for agents.
+  `<base>/llms-full.txt` adds parameters, auth mode, tier and scopes.
+- `<base>/docs` is the interactive reference. `<base>/v1/openapi.json` is
+  the OpenAPI document; the SDK's models are generated from it.

vocalstack-1.0.0a0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vocalstack"
+version = "1.0.0a0"
+description = "VocalStack speech API SDK (asyncio): one client grouped by resource, typed models from the API contract, realtime WebSocket streaming."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=13",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+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", "README.md", "SKILL.md", "skills", "pyproject.toml"]