giggy 0.1.2__tar.gz

giggy-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: Python SDK CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+      - name: Test
+        run: python -m unittest discover -s tests -v
+      - name: Build package
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Verify installed wheel contains STT
+        run: |
+          python -m pip install --force-reinstall --no-deps dist/*.whl
+          cd "$(mktemp -d)"
+          python -c "from giggy import Giggy; c=Giggy(api_key='test-key'); assert all(hasattr(c.transcriptions, m) for m in ['submit','transcribe','get','result','stream','live','send_live_frame'])"

giggy-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish Python SDK
+
+on:
+  push:
+    tags:
+      - "py-v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches package version
+        run: |
+          VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$GITHUB_REF_NAME" = "py-v$VERSION"
+      - name: Install build tools
+        run: python -m pip install build twine
+      - name: Run tests
+        run: |
+          python -m pip install -e .
+          python -m unittest discover -s tests -v
+      - name: Build
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

giggy-0.1.2/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.wheel-venv/
+.env
+.env.*
+speech.mp3
+speech.pcm
+speech.wav
+venv/

giggy-0.1.2/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2026 Giggy
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

giggy-0.1.2/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: giggy
+Version: 0.1.2
+Summary: Official Python SDK for Giggy text-to-speech and speech-to-text.
+Project-URL: Documentation, https://giggy.ai/docs/speech-api
+Project-URL: Repository, https://github.com/giggy-ai/giggy-python
+Project-URL: Issues, https://github.com/giggy-ai/giggy-python/issues
+Author: Giggy
+License-Expression: ISC
+License-File: LICENSE
+Keywords: giggy,speech,speech-to-text,stt,text-to-speech,tts,voice-ai
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Giggy Python SDK
+
+Official Python SDK for the Giggy speech API: text-to-speech and recorded-audio transcription.
+
+## Install
+
+```bash
+python -m pip install giggy==0.1.2
+```
+
+Check `python -m pip index versions giggy` for release availability. The source installation below is also available for development.
+
+## Install from source
+
+```bash
+git clone https://github.com/giggy-ai/giggy-python.git
+cd giggy-python
+python -m pip install .
+```
+
+Requires Python 3.10 or newer. Create a Giggy API key in your Giggy account. The account voice endpoint `GET https://giggy.ai/v1/voices` requires that key as a bearer token; use `voices[].voice_id` as the `voice_id` UUID. Keep API keys server-side.
+
+```bash
+export GIGGY_API_KEY="giggy_sk_..."
+export GIGGY_VOICE_ID="your-voice-uuid"
+```
+
+## Generate speech
+
+```python
+import os
+from pathlib import Path
+from giggy import Giggy
+
+giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"])
+audio = giggy.speech.create(
+    text="Hello from Giggy.",
+    voice_id=os.environ["GIGGY_VOICE_ID"],
+)
+Path("speech.mp3").write_bytes(audio)
+```
+
+## Stream speech
+
+```python
+with giggy.speech.stream(
+    text="Streaming from Giggy.",
+    voice_id=os.environ["GIGGY_VOICE_ID"],
+) as response:
+    with open("speech.pcm", "wb") as output:
+        while chunk := response.read(65536):
+            output.write(chunk)
+```
+
+Streaming requests do not send an idempotency header. The SDK has no automatic retries.
+
+## Transcribe a recording in one SDK call
+
+Prepare a WAV file with signed PCM16, mono, 16 kHz audio. Batch is free for 0.5–60 seconds; Fast accepts 0.5 seconds–12 hours and uses credits. The SDK reads the WAV in bounded chunks instead of loading the whole recording into memory.
+
+```python
+import os
+from giggy import Giggy
+
+giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"])
+print(giggy.transcriptions.transcribe("recording.wav", mode="batch")["text"])
+```
+
+`transcribe()` submits once, polls the durable generation, then fetches its signed transcript URL without forwarding your API key. It stops on failure or after a configurable `timeout` (default 30 minutes); its failure message includes the generation UUID so you can inspect the operation. For submit-now/fetch-later workflows, use `submit()`, `get()`, and `result()` separately. A completed generation can have no downloadable result after retention cleanup. For a paid recording, pass `mode="fast"`. Pass `language="en"` when you know the language; omit it for automatic detection. `client_request_id` accepts a caller-supplied UUID but does not make ambiguous upload retries safe. The SDK does not retry automatically.
+
+### Prepare a compatible WAV
+
+The API accepts signed 16-bit PCM, mono, 16 kHz WAV for this path. For MP3, M4A, stereo, or another sample rate, convert before calling the SDK; this is a local preparation step, not another Giggy endpoint:
+
+```bash
+ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le recording.wav
+ffprobe -v error -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 recording.wav
+```
+
+Check that `ffprobe` reports `pcm_s16le`, `16000`, and `1`. Use a 0.5–60 second file for Batch. If the server rejects the upload, check the WAV format and duration first; a file renamed `.wav` is not converted. Keep the input recording and the returned generation UUID until the result has been verified.
+
+## Stream transcript revisions from an uploaded WAV
+
+Uploaded-recording Streaming uses the same WAV requirements and is paid. It sends cumulative provisional text over server-sent events. Replace displayed text with each newer `transcript_chunk`; do not append it. Completion must be checked through the durable generation before using the canonical result.
+
+```python
+with giggy.transcriptions.stream("recording.wav") as events:
+    generation_uuid = None
+    for event, data in events:
+        if event == "generation_created":
+            generation_uuid = data["generation"]["generation_uuid"]
+        elif event == "transcript_chunk":
+            print("Replace preview:", data["text"])
+    if not generation_uuid:
+        raise RuntimeError("No admitted generation")
+    print("Final:", giggy.transcriptions.result(generation_uuid)["text"])
+```
+
+`stream()` parses SSE frames and closes the response when its context exits. An interrupted or failed stream must be reconciled through `get()`.
+
+## Live microphone PCM session
+
+`live()` opens the existing paid Streaming SSE admission. This complete example records ten seconds from a microphone that supports mono 16 kHz PCM16. Install `sounddevice` (`python -m pip install sounddevice`) and allow microphone access first. The API key stays in the server-side Python process. The sender runs concurrently with the event reader, waits for `microphone_ready`, sends 100 ms frames in order, and sends a final empty frame. Run this with `GIGGY_API_KEY` set:
+
+```python
+import os
+from threading import Thread
+import sounddevice as sd
+from giggy import Giggy
+
+giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"])
+errors = []
+sender = None
+generation_uuid = None
+
+with giggy.transcriptions.live() as events:
+    for event, data in events:
+        if event == "generation_created":
+            generation_uuid = data["generation"]["generation_uuid"]
+        elif event == "microphone_ready":
+            ready = dict(data)
+
+            def send_audio():
+                try:
+                    with sd.RawInputStream(samplerate=16000, channels=1, dtype="int16", blocksize=1600) as microphone:
+                        for sequence in range(100):
+                            pcm, overflowed = microphone.read(1600)
+                            if overflowed:
+                                raise RuntimeError("Microphone capture overflowed")
+                            giggy.transcriptions.send_live_frame(
+                                generation_uuid=ready["generation_uuid"], input_token=ready["input_token"],
+                                sequence=sequence, pcm=bytes(pcm))
+                        giggy.transcriptions.send_live_frame(
+                            generation_uuid=ready["generation_uuid"], input_token=ready["input_token"],
+                            sequence=100, pcm=b"", complete=True)
+                except Exception as error:
+                    errors.append(error)
+
+            sender = Thread(target=send_audio)
+            sender.start()
+        elif event == "transcript_chunk":
+            print("Replace preview:", data["text"])
+
+if sender:
+    sender.join()
+if errors:
+    raise errors[0]
+if not generation_uuid:
+    raise RuntimeError("No admitted generation")
+print("Final:", giggy.transcriptions.result(generation_uuid)["text"])
+```
+
+Each frame is at most 32,000 bytes. Await acceptance before incrementing `sequence`. Closing the live stream before completion cancels unfinished work. Do not reconnect or retry an ambiguously accepted frame. See the [full live input contract](https://giggy.ai/docs/speech-api#api-stt-streaming) for readiness, framing, duration, cancellation, and billing. The SDK does not implement microphone capture or turn detection; `sounddevice` is an example-only dependency.
+
+## Related resources
+
+- [JavaScript/TypeScript SDK](https://github.com/giggy-ai/giggy-js)
+- [Runnable integration examples](https://github.com/giggy-ai/giggy-examples)
+- [Giggy MCP](https://github.com/giggy-ai/giggy-mcp)
+
+## Transcription method reference
+
+All methods belong to `giggy.transcriptions`. SDK defaults select free Batch; the REST endpoint defaults to paid Fast.
+
+| Method | Inputs and defaults | Returns |
+| --- | --- | --- |
+| `transcribe(audio_path, *, mode="batch", language=None, client_request_id=None, poll_interval=2.5, timeout=1800)` | Local WAV; Batch or Fast; finite positive seconds | Final transcript dictionary after one submission |
+| `submit(audio_path, *, mode="batch", language=None, client_request_id=None, timeout=1800)` | Local WAV; one admission; network inactivity timeout in seconds | Admission dictionary containing `generation.generation_uuid` |
+| `get(generation_uuid, *, timeout=30)` | UUID; one status request | Generation dictionary with `status` and optional `result.url` |
+| `result(generation_uuid, *, timeout=30)` | A completed generation; status and signed-artifact retrieval share the timeout budget | Transcript dictionary; key is not sent to the artifact host |
+| `stream(audio_path, *, language=None, client_request_id=None)` | Completed WAV; paid Streaming | Context manager yielding `(event, data)` pairs |
+| `live(*, client_request_id=None)` | Paid live admission; automatic language detection | Context manager yielding the same event pairs |
+| `send_live_frame(*, generation_uuid, input_token, sequence, pcm, complete=False)` | Ordered PCM16 bytes; maximum 32,000 bytes, even length; empty only for completion | Accepted response dictionary |
+
+`transcribe(timeout=...)` starts its wall-clock deadline before upload and bounds waiting for submission, status and artifact I/O. Python uses one bounded I/O thread for this method; on timeout it stops waiting and cancels pending calls, while an in-flight blocking request may finish later. A timeout does not cancel an admitted recording. The exception includes its UUID when admission was received. Individual `submit/get/result` network timeouts also bound socket inactivity; use `transcribe` when you need a deadline for the complete workflow.
+
+The existing events are `generation_created` (admitted generation), `microphone_ready` (UUID, attempt and private input token), `transcript_chunk` (cumulative text, sequence, replace=true and complete), and `generation_updated` (status and optional generation). An event's `complete` flag is not durable generation completion. After EOF, inspect `get()` and fetch `result()` only after `status=completed`.
+These pairs are annotated with the exported `TranscriptionEvent` union and `MicrophoneReady`, `TranscriptChunk`, `GenerationUpdated`, and `TranscriptionAdmission` TypedDict payloads. Unknown named events raise an explicit contract error; heartbeat comments are ignored.
+
+## Troubleshooting and migration
+
+| Symptom | Action |
+| --- | --- |
+| HTTP 401/403 | Check the key and its owning Personal space or Workspace. Never substitute another user's key. |
+| HTTP 429 | Stop new submissions and honor the server response. An unambiguous rejection is different from an upload whose acceptance is unknown. |
+| Timeout before a UUID | Keep the original WAV and request identity; inspect History before another submission. `client_request_id` is not an idempotency guarantee. |
+| Timeout or SSE EOF after a UUID | Call `get(uuid)`; the recording may still be queued or processing. Do not upload it again automatically. |
+| Completed generation without a result URL, or expired signed URL | Read current status again using the owning key. Use a refreshed result URL if one exists; retention/deletion can make the content permanently unavailable. |
+| Live sender fails | Exit the live context to close its SSE connection, then reconcile the UUID. Closing unfinished live input invokes canonical cancellation; closing uploaded-WAV SSE does not. |
+| Empty final text | The valid recording contained no detected speech. Check the recording; do not invent a transcript. |
+
+HTTP failures raise `GiggyAPIError` with status and raw response body. Invalid parameters raise `ValueError`. Deadline expiry raises `TimeoutError`; malformed responses, unavailable results and durable failed/cancelled/admission_failed operations raise `RuntimeError`. Avoid logging live input tokens or signed URLs.
+
+When migrating from AssemblyAI, replace `transcriber.transcribe(audio)` with `giggy.transcriptions.transcribe(wav_path)` and `transcript.text` with `result["text"]`. Convert MP3/video/URL inputs locally to PCM16 mono 16 kHz WAV before submitting. Speaker labels, word times, confidence, subtitle exports and speech-analysis options have no equivalent in this transcript contract; remove those options and explain the difference to your application users. Map provisional turn text to cumulative `transcript_chunk` revisions, and explicitly finish each live input within Giggy's 30-second audio/35-second readiness limit.
+
+For complete commands and recording-to-text applications, see the [Python recording walkthrough](https://github.com/giggy-ai/giggy-examples/tree/main/python/basic-tts#transcribe-a-recording) and [framework STT guide](https://github.com/giggy-ai/giggy-examples#stt-in-voice-agent-frameworks).

giggy-0.1.2/README.md

@@ -0,0 +1,196 @@
+# Giggy Python SDK
+
+Official Python SDK for the Giggy speech API: text-to-speech and recorded-audio transcription.
+
+## Install
+
+```bash
+python -m pip install giggy==0.1.2
+```
+
+Check `python -m pip index versions giggy` for release availability. The source installation below is also available for development.
+
+## Install from source
+
+```bash
+git clone https://github.com/giggy-ai/giggy-python.git
+cd giggy-python
+python -m pip install .
+```
+
+Requires Python 3.10 or newer. Create a Giggy API key in your Giggy account. The account voice endpoint `GET https://giggy.ai/v1/voices` requires that key as a bearer token; use `voices[].voice_id` as the `voice_id` UUID. Keep API keys server-side.
+
+```bash
+export GIGGY_API_KEY="giggy_sk_..."
+export GIGGY_VOICE_ID="your-voice-uuid"
+```
+
+## Generate speech
+
+```python
+import os
+from pathlib import Path
+from giggy import Giggy
+
+giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"])
+audio = giggy.speech.create(
+    text="Hello from Giggy.",
+    voice_id=os.environ["GIGGY_VOICE_ID"],
+)
+Path("speech.mp3").write_bytes(audio)
+```
+
+## Stream speech
+
+```python
+with giggy.speech.stream(
+    text="Streaming from Giggy.",
+    voice_id=os.environ["GIGGY_VOICE_ID"],
+) as response:
+    with open("speech.pcm", "wb") as output:
+        while chunk := response.read(65536):
+            output.write(chunk)
+```
+
+Streaming requests do not send an idempotency header. The SDK has no automatic retries.
+
+## Transcribe a recording in one SDK call
+
+Prepare a WAV file with signed PCM16, mono, 16 kHz audio. Batch is free for 0.5–60 seconds; Fast accepts 0.5 seconds–12 hours and uses credits. The SDK reads the WAV in bounded chunks instead of loading the whole recording into memory.
+
+```python
+import os
+from giggy import Giggy
+
+giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"])
+print(giggy.transcriptions.transcribe("recording.wav", mode="batch")["text"])
+```
+
+`transcribe()` submits once, polls the durable generation, then fetches its signed transcript URL without forwarding your API key. It stops on failure or after a configurable `timeout` (default 30 minutes); its failure message includes the generation UUID so you can inspect the operation. For submit-now/fetch-later workflows, use `submit()`, `get()`, and `result()` separately. A completed generation can have no downloadable result after retention cleanup. For a paid recording, pass `mode="fast"`. Pass `language="en"` when you know the language; omit it for automatic detection. `client_request_id` accepts a caller-supplied UUID but does not make ambiguous upload retries safe. The SDK does not retry automatically.
+
+### Prepare a compatible WAV
+
+The API accepts signed 16-bit PCM, mono, 16 kHz WAV for this path. For MP3, M4A, stereo, or another sample rate, convert before calling the SDK; this is a local preparation step, not another Giggy endpoint:
+
+```bash
+ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le recording.wav
+ffprobe -v error -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 recording.wav
+```
+
+Check that `ffprobe` reports `pcm_s16le`, `16000`, and `1`. Use a 0.5–60 second file for Batch. If the server rejects the upload, check the WAV format and duration first; a file renamed `.wav` is not converted. Keep the input recording and the returned generation UUID until the result has been verified.
+
+## Stream transcript revisions from an uploaded WAV
+
+Uploaded-recording Streaming uses the same WAV requirements and is paid. It sends cumulative provisional text over server-sent events. Replace displayed text with each newer `transcript_chunk`; do not append it. Completion must be checked through the durable generation before using the canonical result.
+
+```python
+with giggy.transcriptions.stream("recording.wav") as events:
+    generation_uuid = None
+    for event, data in events:
+        if event == "generation_created":
+            generation_uuid = data["generation"]["generation_uuid"]
+        elif event == "transcript_chunk":
+            print("Replace preview:", data["text"])
+    if not generation_uuid:
+        raise RuntimeError("No admitted generation")
+    print("Final:", giggy.transcriptions.result(generation_uuid)["text"])
+```
+
+`stream()` parses SSE frames and closes the response when its context exits. An interrupted or failed stream must be reconciled through `get()`.
+
+## Live microphone PCM session
+
+`live()` opens the existing paid Streaming SSE admission. This complete example records ten seconds from a microphone that supports mono 16 kHz PCM16. Install `sounddevice` (`python -m pip install sounddevice`) and allow microphone access first. The API key stays in the server-side Python process. The sender runs concurrently with the event reader, waits for `microphone_ready`, sends 100 ms frames in order, and sends a final empty frame. Run this with `GIGGY_API_KEY` set:
+
+```python
+import os
+from threading import Thread
+import sounddevice as sd
+from giggy import Giggy
+
+giggy = Giggy(api_key=os.environ["GIGGY_API_KEY"])
+errors = []
+sender = None
+generation_uuid = None
+
+with giggy.transcriptions.live() as events:
+    for event, data in events:
+        if event == "generation_created":
+            generation_uuid = data["generation"]["generation_uuid"]
+        elif event == "microphone_ready":
+            ready = dict(data)
+
+            def send_audio():
+                try:
+                    with sd.RawInputStream(samplerate=16000, channels=1, dtype="int16", blocksize=1600) as microphone:
+                        for sequence in range(100):
+                            pcm, overflowed = microphone.read(1600)
+                            if overflowed:
+                                raise RuntimeError("Microphone capture overflowed")
+                            giggy.transcriptions.send_live_frame(
+                                generation_uuid=ready["generation_uuid"], input_token=ready["input_token"],
+                                sequence=sequence, pcm=bytes(pcm))
+                        giggy.transcriptions.send_live_frame(
+                            generation_uuid=ready["generation_uuid"], input_token=ready["input_token"],
+                            sequence=100, pcm=b"", complete=True)
+                except Exception as error:
+                    errors.append(error)
+
+            sender = Thread(target=send_audio)
+            sender.start()
+        elif event == "transcript_chunk":
+            print("Replace preview:", data["text"])
+
+if sender:
+    sender.join()
+if errors:
+    raise errors[0]
+if not generation_uuid:
+    raise RuntimeError("No admitted generation")
+print("Final:", giggy.transcriptions.result(generation_uuid)["text"])
+```
+
+Each frame is at most 32,000 bytes. Await acceptance before incrementing `sequence`. Closing the live stream before completion cancels unfinished work. Do not reconnect or retry an ambiguously accepted frame. See the [full live input contract](https://giggy.ai/docs/speech-api#api-stt-streaming) for readiness, framing, duration, cancellation, and billing. The SDK does not implement microphone capture or turn detection; `sounddevice` is an example-only dependency.
+
+## Related resources
+
+- [JavaScript/TypeScript SDK](https://github.com/giggy-ai/giggy-js)
+- [Runnable integration examples](https://github.com/giggy-ai/giggy-examples)
+- [Giggy MCP](https://github.com/giggy-ai/giggy-mcp)
+
+## Transcription method reference
+
+All methods belong to `giggy.transcriptions`. SDK defaults select free Batch; the REST endpoint defaults to paid Fast.
+
+| Method | Inputs and defaults | Returns |
+| --- | --- | --- |
+| `transcribe(audio_path, *, mode="batch", language=None, client_request_id=None, poll_interval=2.5, timeout=1800)` | Local WAV; Batch or Fast; finite positive seconds | Final transcript dictionary after one submission |
+| `submit(audio_path, *, mode="batch", language=None, client_request_id=None, timeout=1800)` | Local WAV; one admission; network inactivity timeout in seconds | Admission dictionary containing `generation.generation_uuid` |
+| `get(generation_uuid, *, timeout=30)` | UUID; one status request | Generation dictionary with `status` and optional `result.url` |
+| `result(generation_uuid, *, timeout=30)` | A completed generation; status and signed-artifact retrieval share the timeout budget | Transcript dictionary; key is not sent to the artifact host |
+| `stream(audio_path, *, language=None, client_request_id=None)` | Completed WAV; paid Streaming | Context manager yielding `(event, data)` pairs |
+| `live(*, client_request_id=None)` | Paid live admission; automatic language detection | Context manager yielding the same event pairs |
+| `send_live_frame(*, generation_uuid, input_token, sequence, pcm, complete=False)` | Ordered PCM16 bytes; maximum 32,000 bytes, even length; empty only for completion | Accepted response dictionary |
+
+`transcribe(timeout=...)` starts its wall-clock deadline before upload and bounds waiting for submission, status and artifact I/O. Python uses one bounded I/O thread for this method; on timeout it stops waiting and cancels pending calls, while an in-flight blocking request may finish later. A timeout does not cancel an admitted recording. The exception includes its UUID when admission was received. Individual `submit/get/result` network timeouts also bound socket inactivity; use `transcribe` when you need a deadline for the complete workflow.
+
+The existing events are `generation_created` (admitted generation), `microphone_ready` (UUID, attempt and private input token), `transcript_chunk` (cumulative text, sequence, replace=true and complete), and `generation_updated` (status and optional generation). An event's `complete` flag is not durable generation completion. After EOF, inspect `get()` and fetch `result()` only after `status=completed`.
+These pairs are annotated with the exported `TranscriptionEvent` union and `MicrophoneReady`, `TranscriptChunk`, `GenerationUpdated`, and `TranscriptionAdmission` TypedDict payloads. Unknown named events raise an explicit contract error; heartbeat comments are ignored.
+
+## Troubleshooting and migration
+
+| Symptom | Action |
+| --- | --- |
+| HTTP 401/403 | Check the key and its owning Personal space or Workspace. Never substitute another user's key. |
+| HTTP 429 | Stop new submissions and honor the server response. An unambiguous rejection is different from an upload whose acceptance is unknown. |
+| Timeout before a UUID | Keep the original WAV and request identity; inspect History before another submission. `client_request_id` is not an idempotency guarantee. |
+| Timeout or SSE EOF after a UUID | Call `get(uuid)`; the recording may still be queued or processing. Do not upload it again automatically. |
+| Completed generation without a result URL, or expired signed URL | Read current status again using the owning key. Use a refreshed result URL if one exists; retention/deletion can make the content permanently unavailable. |
+| Live sender fails | Exit the live context to close its SSE connection, then reconcile the UUID. Closing unfinished live input invokes canonical cancellation; closing uploaded-WAV SSE does not. |
+| Empty final text | The valid recording contained no detected speech. Check the recording; do not invent a transcript. |
+
+HTTP failures raise `GiggyAPIError` with status and raw response body. Invalid parameters raise `ValueError`. Deadline expiry raises `TimeoutError`; malformed responses, unavailable results and durable failed/cancelled/admission_failed operations raise `RuntimeError`. Avoid logging live input tokens or signed URLs.
+
+When migrating from AssemblyAI, replace `transcriber.transcribe(audio)` with `giggy.transcriptions.transcribe(wav_path)` and `transcript.text` with `result["text"]`. Convert MP3/video/URL inputs locally to PCM16 mono 16 kHz WAV before submitting. Speaker labels, word times, confidence, subtitle exports and speech-analysis options have no equivalent in this transcript contract; remove those options and explain the difference to your application users. Map provisional turn text to cumulative `transcript_chunk` revisions, and explicitly finish each live input within Giggy's 30-second audio/35-second readiness limit.
+
+For complete commands and recording-to-text applications, see the [Python recording walkthrough](https://github.com/giggy-ai/giggy-examples/tree/main/python/basic-tts#transcribe-a-recording) and [framework STT guide](https://github.com/giggy-ai/giggy-examples#stt-in-voice-agent-frameworks).

giggy-0.1.2/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "giggy"
+version = "0.1.2"
+description = "Official Python SDK for Giggy text-to-speech and speech-to-text."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "ISC"
+authors = [{ name = "Giggy" }]
+keywords = ["giggy", "text-to-speech", "speech-to-text", "tts", "stt", "speech", "voice-ai"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://giggy.ai/docs/speech-api"
+Repository = "https://github.com/giggy-ai/giggy-python"
+Issues = "https://github.com/giggy-ai/giggy-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/giggy"]

giggy-0.1.2/src/giggy/__init__.py

@@ -0,0 +1,4 @@
+from .client import Giggy, GenerationUpdated, MicrophoneReady, TranscriptChunk, TranscriptionAdmission, TranscriptionEvent
+from .errors import GiggyAPIError
+
+__all__ = ["Giggy", "GiggyAPIError", "GenerationUpdated", "MicrophoneReady", "TranscriptChunk", "TranscriptionAdmission", "TranscriptionEvent"]

giggy-0.1.2/src/giggy/client.py

@@ -0,0 +1,366 @@
+from collections.abc import Iterator
+from base64 import b64encode
+from contextlib import contextmanager
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutError
+import json
+import math
+from pathlib import Path
+import re
+import time
+from typing import BinaryIO, Literal, TypeAlias, TypedDict, cast
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+from urllib.parse import urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+from uuid import RFC_4122, UUID, uuid4
+
+from .errors import GiggyAPIError
+
+class MicrophoneReady(TypedDict):
+    generation_uuid: str
+    attempt: int
+    input_token: str
+
+class TranscriptChunk(TypedDict):
+    generation_uuid: str
+    attempt: int
+    text: str
+    sequence: int
+    replace: Literal[True]
+    complete: bool
+
+class GenerationUpdated(TypedDict, total=False):
+    generation_uuid: str
+    status: str
+    attempt: int
+    generation: dict
+
+class TranscriptionAdmission(TypedDict):
+    generation: dict
+
+TranscriptionEvent: TypeAlias = (
+    tuple[Literal["generation_created"], TranscriptionAdmission]
+    | tuple[Literal["microphone_ready"], MicrophoneReady]
+    | tuple[Literal["transcript_chunk"], TranscriptChunk]
+    | tuple[Literal["generation_updated"], GenerationUpdated]
+)
+
+class Speech:
+    def __init__(self, *, api_key: str, base_url: str) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+
+    def _request(
+        self,
+        *,
+        text: str,
+        voice_id: str,
+        mode: str,
+        output_format: str,
+        speed: float | None,
+        idempotency_key: str | None = None,
+    ):
+        if not text.strip():
+            raise ValueError("text must not be empty")
+        if not voice_id.strip():
+            raise ValueError("voice_id must not be empty")
+
+        payload: dict[str, object] = {
+            "text": text,
+            "voice_id": voice_id,
+            "model_id": "giggyspeech",
+            "mode": mode,
+            "output_format": output_format,
+        }
+        if speed is not None:
+            payload["voice_settings"] = {"speed": speed}
+
+        headers = {
+            "xi-api-key": self._api_key,
+            "content-type": "application/json",
+        }
+        if idempotency_key is not None:
+            headers["idempotency-key"] = idempotency_key
+
+        request = Request(
+            self._base_url + "/text-to-speech",
+            data=json.dumps(payload).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        try:
+            return urlopen(request, timeout=120)
+        except HTTPError as error:
+            body = error.read().decode("utf-8", errors="replace")
+            raise GiggyAPIError(error.code, body) from error
+
+    def create(
+        self,
+        *,
+        text: str,
+        voice_id: str,
+        mode: Literal["batch", "fast"] = "batch",
+        output_format: str = "mp3_24000_160",
+        speed: float | None = None,
+        idempotency_key: str | None = None,
+    ) -> bytes:
+        response = self._request(
+            text=text,
+            voice_id=voice_id,
+            mode=mode,
+            output_format=output_format,
+            speed=speed,
+            idempotency_key=(idempotency_key if idempotency_key is not None else str(uuid4())),
+        )
+        with response:
+            return response.read()
+
+    @contextmanager
+    def stream(
+        self,
+        *,
+        text: str,
+        voice_id: str,
+        output_format: str = "pcm_24000",
+        speed: float | None = None,
+    ) -> Iterator[BinaryIO]:
+        response = self._request(
+            text=text,
+            voice_id=voice_id,
+            mode="streaming",
+            output_format=output_format,
+            speed=speed,
+        )
+        try:
+            yield response
+        finally:
+            response.close()
+
+
+class Transcriptions:
+    def __init__(self, *, api_key: str, base_url: str) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+
+    def _upload(self, audio_path: str | Path, *, mode: str, language: str | None,
+                client_request_id: str | None, timeout: float = 1800):
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be finite and positive")
+        if mode not in ("batch", "fast", "streaming"):
+            raise ValueError("mode must be batch, fast, or streaming")
+        if language is not None and not language.strip():
+            raise ValueError("language must not be blank")
+        if client_request_id is not None:
+            parsed_id = UUID(client_request_id)
+            if parsed_id.variant != RFC_4122 or parsed_id.version not in (1, 2, 3, 4, 5):
+                raise ValueError("client_request_id must be an RFC 4122 UUID v1–v5")
+            client_request_id = str(parsed_id)
+        query = {"mode": mode}
+        if language is not None:
+            query["language"] = language
+        if client_request_id is not None:
+            query["client_request_id"] = client_request_id
+        path = Path(audio_path)
+        with path.open("rb") as audio:
+            request = Request(
+                self._base_url + "/audio/transcriptions?" + urlencode(query),
+                data=iter(lambda: audio.read(1024 * 1024), b""),
+                headers={"xi-api-key": self._api_key, "Content-Type": "audio/wav",
+                         "Content-Length": str(path.stat().st_size)},
+                method="POST",
+            )
+            try:
+                return urlopen(request, timeout=timeout)
+            except HTTPError as error:
+                raise GiggyAPIError(error.code, error.read().decode("utf-8", errors="replace")) from error
+
+    def submit(self, audio_path: str | Path, *, mode: Literal["batch", "fast"] = "batch",
+               language: str | None = None, client_request_id: str | None = None,
+               timeout: float = 1800) -> dict:
+        """Admit a WAV recording; retrieve its transcript after durable completion."""
+        with self._upload(audio_path, mode=mode, language=language,
+                          client_request_id=client_request_id, timeout=timeout) as response:
+            if response.status != 202:
+                raise RuntimeError(f"Expected HTTP 202 admission, got {response.status}")
+            admission = json.load(response)
+        if not isinstance(admission, dict) or not isinstance(admission.get("generation"), dict) or not isinstance(admission["generation"].get("generation_uuid"), str) or not isinstance(admission["generation"].get("status"), str):
+            raise RuntimeError("Giggy returned an invalid transcription admission")
+        return admission
+
+    def transcribe(self, audio_path: str | Path, *, mode: Literal["batch", "fast"] = "batch",
+                   language: str | None = None, client_request_id: str | None = None,
+                   poll_interval: float = 2.5, timeout: float = 1800) -> dict:
+        """Submit once, wait for the durable generation, and read its transcript."""
+        if not math.isfinite(poll_interval) or not math.isfinite(timeout) or poll_interval <= 0 or timeout <= 0:
+            raise ValueError("poll_interval and timeout must be finite and positive")
+        deadline = time.monotonic() + timeout
+        generation_uuid = None
+        executor = ThreadPoolExecutor(max_workers=1)
+        try:
+            admission = executor.submit(self.submit, audio_path, mode=mode, language=language,
+                                        client_request_id=client_request_id, timeout=timeout).result(timeout=timeout)
+            generation_uuid = admission["generation"]["generation_uuid"]
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError()
+                generation = executor.submit(self.get, generation_uuid, timeout=min(30, remaining)).result(timeout=remaining)
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError()
+                if generation["status"] == "completed":
+                    return executor.submit(self.result, generation_uuid, timeout=remaining).result(timeout=remaining)
+                if generation["status"] in ("failed", "cancelled", "admission_failed"):
+                    raise RuntimeError(f"Transcription {generation_uuid} is {generation['status']}")
+                time.sleep(min(poll_interval, remaining))
+        except (TimeoutError, FutureTimeoutError) as error:
+            identity = generation_uuid or "admission (generation UUID not received)"
+            if time.monotonic() < deadline:
+                raise TimeoutError(f"Transcription {identity} network I/O timed out; reconcile the existing operation before resubmitting") from error
+            raise TimeoutError(f"Transcription {identity} did not complete within {timeout} seconds; do not resubmit an ambiguous upload") from error
+        finally:
+            executor.shutdown(wait=False, cancel_futures=True)
+
+    def get(self, generation_uuid: str, *, timeout: float = 30) -> dict:
+        """Read the canonical generation status without polling or retrying."""
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be finite and positive")
+        generation_uuid = str(UUID(generation_uuid))
+        request = Request(self._base_url + "/generations/" + generation_uuid,
+                          headers={"xi-api-key": self._api_key})
+        try:
+            with urlopen(request, timeout=timeout) as response:
+                payload = json.load(response)
+        except HTTPError as error:
+            raise GiggyAPIError(error.code, error.read().decode("utf-8", errors="replace")) from error
+        generation = payload.get("generation") if isinstance(payload, dict) else None
+        if not isinstance(generation, dict) or generation.get("generation_uuid") != generation_uuid or not isinstance(generation.get("status"), str):
+            raise RuntimeError("Giggy returned an invalid generation")
+        return generation
+
+    def result(self, generation_uuid: str, *, timeout: float = 30) -> dict:
+        """Fetch the signed transcript only after the generation completed."""
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be finite and positive")
+        deadline = time.monotonic() + timeout
+        generation = self.get(generation_uuid, timeout=timeout)
+        if generation.get("status") != "completed":
+            raise RuntimeError(f"Transcription is {generation.get('status')}")
+        url = (generation.get("result") or {}).get("url")
+        if not isinstance(url, str) or not url.startswith("https://"):
+            raise RuntimeError("Transcript is no longer available")
+        try:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("Transcript retrieval timed out")
+            with urlopen(Request(url), timeout=remaining) as response:
+                transcript = json.load(response)
+        except HTTPError as error:
+            raise GiggyAPIError(error.code, error.read().decode("utf-8", errors="replace")) from error
+        if not isinstance(transcript, dict) or not isinstance(transcript.get("text"), str):
+            raise RuntimeError("Giggy returned an invalid transcript")
+        return transcript
+
+    @contextmanager
+    def stream(self, audio_path: str | Path, *, language: str | None = None,
+               client_request_id: str | None = None) -> Iterator[Iterator[TranscriptionEvent]]:
+        """Stream parsed SSE events while processing an uploaded WAV recording."""
+        response = self._upload(audio_path, mode="streaming", language=language,
+                                client_request_id=client_request_id)
+        try:
+            if response.status != 200 or "text/event-stream" not in response.headers.get("content-type", ""):
+                raise RuntimeError("Giggy did not return a transcript event stream")
+            yield self._events(response)
+        finally:
+            response.close()
+
+    @contextmanager
+    def live(self, *, client_request_id: str | None = None) -> Iterator[Iterator[TranscriptionEvent]]:
+        """Open a paid live microphone SSE session; send frames separately after readiness."""
+        if client_request_id is not None:
+            parsed_id = UUID(client_request_id)
+            if parsed_id.variant != RFC_4122 or parsed_id.version not in (1, 2, 3, 4, 5):
+                raise ValueError("client_request_id must be an RFC 4122 UUID v1–v5")
+            client_request_id = str(parsed_id)
+        payload = {"mode": "streaming", "microphone": True}
+        if client_request_id is not None:
+            payload["client_request_id"] = client_request_id
+        request = Request(
+            self._base_url + "/audio/transcriptions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"xi-api-key": self._api_key, "Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            response = urlopen(request, timeout=150)
+        except HTTPError as error:
+            raise GiggyAPIError(error.code, error.read().decode("utf-8", errors="replace")) from error
+        try:
+            if response.status != 200 or "text/event-stream" not in response.headers.get("content-type", ""):
+                raise RuntimeError("Giggy did not return a live transcript event stream")
+            yield self._events(response)
+        finally:
+            response.close()
+
+    def send_live_frame(self, *, generation_uuid: str, input_token: str, sequence: int,
+                        pcm: bytes, complete: bool = False) -> None:
+        """Send one ordered PCM16 frame; the caller must await its acceptance before the next."""
+        generation_uuid = str(UUID(generation_uuid))
+        if not re.fullmatch(r"[0-9a-f]{64}", input_token):
+            raise ValueError("input_token must be the microphone_ready capability")
+        if not isinstance(sequence, int) or isinstance(sequence, bool) or sequence < 0:
+            raise ValueError("sequence must be a nonnegative integer")
+        if not isinstance(pcm, bytes) or len(pcm) > 32000 or len(pcm) % 2 or (not pcm and not complete):
+            raise ValueError("pcm must be an even PCM16 byte frame of at most one second")
+        parsed = urlsplit(self._base_url)
+        if parsed.path.rstrip("/") != "/v1":
+            raise ValueError("base_url must end with /v1 for live input")
+        origin = urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+        request = Request(
+            origin + "/api/generations/" + generation_uuid + "/stt-input",
+            data=json.dumps({"input_token": input_token, "sequence": sequence,
+                             "pcm_base64": b64encode(pcm).decode("ascii"), "complete": complete}).encode("utf-8"),
+            headers={"Content-Type": "application/json", "User-Agent": "giggy-python"},
+            method="POST",
+        )
+        try:
+            with urlopen(request, timeout=10) as response:
+                accepted = json.load(response)
+        except HTTPError as error:
+            raise GiggyAPIError(error.code, error.read().decode("utf-8", errors="replace")) from error
+        if not isinstance(accepted, dict) or accepted.get("ok") is not True:
+            raise RuntimeError("Giggy did not accept the PCM frame")
+
+    def _events(self, response) -> Iterator[TranscriptionEvent]:
+        event = ""
+        data: list[str] = []
+        for raw in response:
+            line = raw.decode("utf-8").rstrip("\r\n")
+            if line == "":
+                if data:
+                    payload = json.loads("\n".join(data))
+                    if not isinstance(payload, dict):
+                        raise RuntimeError("Giggy returned an invalid transcript event")
+                    if event not in ("generation_created", "microphone_ready", "transcript_chunk", "generation_updated"):
+                        raise RuntimeError(f"Unexpected transcript event: {event or '(unnamed)'}; reconcile the generation through get()")
+                    yield cast(TranscriptionEvent, (event, payload))
+                event, data = "", []
+            elif line.startswith("event:"):
+                event = line[6:].strip()
+            elif line.startswith("data:"):
+                data.append(line[5:].lstrip(" "))
+        if data:
+            raise RuntimeError("Transcript event stream ended mid-event")
+
+
+class Giggy:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://giggy.ai/v1",
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("api_key must not be empty")
+        self.speech = Speech(api_key=api_key, base_url=base_url)
+        self.transcriptions = Transcriptions(api_key=api_key, base_url=base_url)

giggy-0.1.2/src/giggy/errors.py

@@ -0,0 +1,7 @@
+class GiggyAPIError(Exception):
+    """An HTTP error returned by the Giggy API."""
+
+    def __init__(self, status_code: int, body: str) -> None:
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"Giggy API returned HTTP {status_code}: {body}")

giggy-0.1.2/tests/test_client.py

@@ -0,0 +1,179 @@
+import json
+import time
+import unittest
+from io import BytesIO
+from unittest.mock import patch
+from urllib.error import HTTPError
+
+from giggy import Giggy, GiggyAPIError
+
+
+class Response(BytesIO):
+    status = 202
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class GiggyClientTests(unittest.TestCase):
+    def setUp(self):
+        self.client = Giggy(api_key="test-key")
+
+    def test_missing_api_key(self):
+        with self.assertRaisesRegex(ValueError, "api_key"):
+            Giggy(api_key=" ")
+
+    def _check_create(self, mode="batch", idempotency_key=None):
+        response = Response(b"audio")
+        with patch("giggy.client.urlopen", return_value=response) as mocked:
+            result = self.client.speech.create(
+                text="hello", voice_id="voice", mode=mode,
+                idempotency_key=idempotency_key,
+            )
+        req = mocked.call_args.args[0]
+        payload = json.loads(req.data)
+        return result, req, payload
+
+    def test_batch_request_mapping_and_automatic_idempotency(self):
+        result, req, payload = self._check_create()
+        self.assertEqual(result, b"audio")
+        self.assertEqual(req.full_url, "https://giggy.ai/v1/text-to-speech")
+        self.assertEqual(payload["mode"], "batch")
+        self.assertEqual(payload["voice_id"], "voice")
+        self.assertTrue(req.get_header("Idempotency-key"))
+
+    def test_fast_request_mapping(self):
+        _, _, payload = self._check_create(mode="fast")
+        self.assertEqual(payload["mode"], "fast")
+
+    def test_supplied_idempotency_key(self):
+        _, req, _ = self._check_create(idempotency_key="my-key")
+        self.assertEqual(req.get_header("Idempotency-key"), "my-key")
+
+    def test_streaming_request_has_no_idempotency_header_and_closes(self):
+        response = Response(b"pcm")
+        with patch("giggy.client.urlopen", return_value=response) as mocked:
+            with self.client.speech.stream(text="hello", voice_id="voice") as body:
+                self.assertEqual(body.read(), b"pcm")
+            req = mocked.call_args.args[0]
+        self.assertEqual(json.loads(req.data)["mode"], "streaming")
+        self.assertIsNone(req.get_header("Idempotency-key"))
+        self.assertTrue(response.closed)
+
+    def test_http_400_raises_structured_error(self):
+        error = HTTPError("url", 400, "bad request", {}, BytesIO(b"invalid"))
+        with patch("giggy.client.urlopen", side_effect=error):
+            with self.assertRaises(GiggyAPIError) as raised:
+                self.client.speech.create(text="hello", voice_id="voice")
+        self.assertEqual(raised.exception.status_code, 400)
+        self.assertIn("invalid", raised.exception.body)
+
+    def test_transcription_submission_streams_wav_and_maps_options(self):
+        from pathlib import Path
+        path = Path("pyproject.toml")
+        generation_id = "00000000-0000-4000-8000-000000000001"
+        captured = {}
+
+        def respond(request, timeout):
+            captured["url"] = request.full_url
+            captured["headers"] = request.headers
+            captured["body"] = b"".join(request.data)
+            return Response(json.dumps({"generation": {"generation_uuid": generation_id, "status": "queued"}}).encode())
+
+        with patch("giggy.client.urlopen", side_effect=respond):
+            admission = self.client.transcriptions.submit(
+                path, mode="fast", language="en", client_request_id=generation_id,
+            )
+        self.assertEqual(admission["generation"]["generation_uuid"], generation_id)
+        self.assertIn("/audio/transcriptions?mode=fast&language=en&client_request_id=", captured["url"])
+        self.assertEqual(captured["headers"]["Xi-api-key"], "test-key")
+        self.assertEqual(captured["body"], path.read_bytes())
+
+    def test_transcription_result_requires_durable_success_and_unsigned_artifact_request(self):
+        generation_id = "00000000-0000-4000-8000-000000000001"
+        artifact_url = "https://example.test/transcript.json"
+        requests = []
+
+        def respond(request, timeout):
+            requests.append(request)
+            if len(requests) == 1:
+                return Response(json.dumps({"generation": {
+                    "generation_uuid": generation_id, "status": "completed", "result": {"url": artifact_url}
+                }}).encode())
+            return Response(b'{"text":"hello","languages":["English"]}')
+
+        with patch("giggy.client.urlopen", side_effect=respond):
+            result = self.client.transcriptions.result(generation_id)
+        self.assertEqual(result["text"], "hello")
+        self.assertEqual(requests[0].get_header("Xi-api-key"), "test-key")
+        self.assertIsNone(requests[1].get_header("Xi-api-key"))
+
+    def test_transcribe_submits_once_and_waits_for_durable_result(self):
+        generation_id = "00000000-0000-4000-8000-000000000001"
+        responses = iter([
+            Response(json.dumps({"generation": {"generation_uuid": generation_id, "status": "queued"}}).encode()),
+            Response(json.dumps({"generation": {"generation_uuid": generation_id, "status": "processing"}}).encode()),
+            Response(json.dumps({"generation": {"generation_uuid": generation_id, "status": "completed"}}).encode()),
+            Response(json.dumps({"generation": {"generation_uuid": generation_id, "status": "completed", "result": {"url": "https://example.test/transcript.json"}}}).encode()),
+            Response(b'{"text":"ready"}'),
+        ])
+        with patch("giggy.client.urlopen", side_effect=lambda request, timeout: next(responses)) as opened, patch("giggy.client.time.sleep") as slept:
+            result = self.client.transcriptions.transcribe("pyproject.toml", poll_interval=0.1)
+        self.assertEqual(result["text"], "ready")
+        self.assertEqual(opened.call_count, 5)
+        self.assertEqual(slept.call_count, 1)
+        started = time.monotonic()
+        with patch.object(self.client.transcriptions, "submit", side_effect=lambda *args, **kwargs: time.sleep(0.15)) as submitted:
+            with self.assertRaisesRegex(TimeoutError, "generation UUID not received"):
+                self.client.transcriptions.transcribe("pyproject.toml", timeout=0.02)
+        self.assertLess(time.monotonic() - started, 0.12)
+        self.assertEqual(submitted.call_count, 1)
+        for invalid in (float("nan"), float("inf"), 0, -1):
+            with self.assertRaises(ValueError):
+                self.client.transcriptions.transcribe("pyproject.toml", timeout=invalid)
+
+    def test_transcription_stream_parses_split_events_and_revisions(self):
+        path = "pyproject.toml"
+        response = Response(b'event: transcript_chunk\r\ndata: {"text":"one","replace":true}\r\n\r\nevent: transcript_chunk\r\ndata: {"text":"one two","replace":true}\r\n\r\n')
+        response.status = 200
+        response.headers = {"content-type": "text/event-stream"}
+        with patch("giggy.client.urlopen", return_value=response):
+            with self.client.transcriptions.stream(path) as events:
+                items = list(events)
+        self.assertEqual([item[1]["text"] for item in items], ["one", "one two"])
+        self.assertTrue(response.closed)
+
+    def test_live_transcription_admission_and_ordered_frame_request(self):
+        generation_id = "00000000-0000-4000-8000-000000000001"
+        token = "a" * 64
+        calls = []
+        event_body = (f'event: microphone_ready\ndata: {{"generation_uuid":"{generation_id}","attempt":1,"input_token":"{token}"}}\n\n').encode()
+        live_response = Response(event_body)
+        live_response.status = 200
+        live_response.headers = {"content-type": "text/event-stream"}
+
+        def respond(request, timeout):
+            calls.append(request)
+            return live_response if len(calls) == 1 else Response(b'{"ok":true}')
+
+        with patch("giggy.client.urlopen", side_effect=respond):
+            with self.client.transcriptions.live(client_request_id=generation_id) as events:
+                event, data = next(events)
+                self.assertEqual(event, "microphone_ready")
+                self.client.transcriptions.send_live_frame(
+                    generation_uuid=data["generation_uuid"], input_token=data["input_token"],
+                    sequence=0, pcm=b"\x01\x00" * 8000, complete=True,
+                )
+        self.assertEqual(json.loads(calls[0].data)["microphone"], True)
+        self.assertEqual(calls[1].full_url, "https://giggy.ai/api/generations/" + generation_id + "/stt-input")
+        self.assertIsNone(calls[1].get_header("Xi-api-key"))
+        self.assertEqual(calls[1].get_header("User-agent"), "giggy-python")
+        self.assertEqual(json.loads(calls[1].data)["sequence"], 0)
+        self.assertTrue(live_response.closed)
+
+
+if __name__ == "__main__":
+    unittest.main()