genblaze-assemblyai 0.3.0__tar.gz

genblaze_assemblyai-0.3.0/.gitignore

@@ -0,0 +1,76 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+wheels/
+/MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE / editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pytype/
+.pyre/
+
+# Linting
+.ruff_cache/
+
+# OS files
+.DS_Store
+Thumbs.db
+ehthumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+credentials.json
+
+# Jupyter
+.ipynb_checkpoints/
+
+# MkDocs build output
+site/
+
+# Claude Code — local/ephemeral
+.claude/settings.local.json
+.claude/worktrees/
+CLAUDE.local.md
+
+# Hypothesis test cache
+.hypothesis/
+
+# Temp files
+*.tmp
+*.bak
+*.log

genblaze_assemblyai-0.3.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: genblaze-assemblyai
+Version: 0.3.0
+Summary: AssemblyAI (speech-to-text / transcription) provider adapter for genblaze
+Project-URL: Homepage, https://github.com/backblaze-labs/genblaze
+Project-URL: Documentation, https://github.com/backblaze-labs/genblaze
+Project-URL: Repository, https://github.com/backblaze-labs/genblaze
+Project-URL: Issues, https://github.com/backblaze-labs/genblaze/issues
+Author-email: Eduardo Pavez <epavez@backblaze.com>
+License-Expression: MIT
+Keywords: ai,assemblyai,audio,c2pa-ready,genai,genblaze,manifest,media,pipeline,provenance,speech-to-text,transcription
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: assemblyai<1,>=0.45
+Requires-Dist: genblaze-core<0.4,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<!-- last_verified: 2026-06-23 -->
+# genblaze-assemblyai
+
+[AssemblyAI](https://www.assemblyai.com/) **speech-to-text / transcription**
+provider adapter for [genblaze](https://github.com/backblaze-labs/genblaze).
+
+This connector is the inverse of every other genblaze adapter: instead of
+*generating* media it *consumes* an audio URL and *produces* a text
+transcript with word-level timings. The transcript lands as a hash-verified
+**TEXT asset** with a provenance manifest, so it composes into pipelines
+(generate audio → transcribe, caption a generated video) and persists to
+Backblaze B2 / S3 like any other genblaze step.
+
+## Install
+
+```bash
+pip install genblaze-assemblyai      # or: pip install "genblaze[assemblyai]"
+export ASSEMBLYAI_API_KEY="..."      # from https://www.assemblyai.com/app/api-keys
+```
+
+## Usage
+
+```python
+from genblaze_core import Modality, Pipeline
+from genblaze_assemblyai import AssemblyAIProvider
+
+run, manifest = (
+    Pipeline("transcribe")
+    .step(
+        AssemblyAIProvider(),
+        model="universal-3-pro",                       # speech_models: universal-3-pro | universal-2
+        prompt="https://example.com/podcast-episode.mp3",  # or params={"audio_url": ...}, or a chained audio input
+        modality=Modality.TEXT,
+        speaker_labels=True,                           # any TranscriptionConfig flag passes through
+    )
+    .run()
+)
+
+asset = run.steps[0].assets[0]
+print(asset.metadata["text"])          # the transcript
+print(asset.audio.word_timings[:3])    # [WordTiming(word=..., start=..., end=...), ...] (seconds)
+print(manifest.canonical_hash)
+```
+
+The audio URL is resolved from (in priority order) `step.inputs[0].url` →
+`step.params["audio_url"]` → `step.prompt`, then SSRF-validated (https:// or
+file:// only) before submission. `step.model` selects the AssemblyAI speech
+model (sent on the SDK's plural `speech_models` field — the live API retired
+the singular `speech_model` field and the `best` / `nano` aliases; current
+values are `universal-3-pro` / `universal-2`); every other
+`TranscriptionConfig` flag (`speaker_labels`, `language_code`,
+audio-intelligence options, …) passes through `step.params`.
+
+## Pricing
+
+The SDK ships no hardcoded prices. AssemblyAI bills per minute of *input*
+audio; the connector captures the input duration in
+`step.provider_payload["audio_duration"]` (seconds) during `fetch_output`.
+Register a recipe at runtime — see
+[`docs/reference/pricing-recipes.md`](https://github.com/backblaze-labs/genblaze/blob/main/docs/reference/pricing-recipes.md)
+("AssemblyAI" section):
+
+```python
+from genblaze_core.providers import per_response_metric
+
+RATE_PER_MINUTE = RATE  # replace RATE with the per-minute USD rate from assemblyai.com/pricing
+
+
+def per_minute(ctx):
+    seconds = ctx.provider_payload.get("audio_duration")
+    return (seconds / 60.0) * RATE_PER_MINUTE if seconds is not None else None
+
+
+provider = AssemblyAIProvider(api_key="...")
+# Speech-model slugs match the connector's family, so register against the
+# concrete slug(s) you use (register_pricing layers onto the family spec).
+for slug in ("universal-3-pro", "universal-2"):
+    provider.models.register_pricing(slug, per_response_metric(per_minute))
+```
+
+## Notes
+
+- **Out of scope for v1:** real-time/streaming transcription, LeMUR
+  (LLM-over-transcript), and first-class SRT/VTT subtitle outputs. Audio-
+  intelligence flags pass through to the API and land in `metadata`.
+
+## Docs
+
+- [AssemblyAI docs](https://www.assemblyai.com/docs)
+- [Transcript API reference](https://www.assemblyai.com/docs/api-reference/transcripts/get)
+- genblaze [new-provider guide](https://github.com/backblaze-labs/genblaze/blob/main/docs/guides/new-provider.md)

genblaze_assemblyai-0.3.0/README.md

@@ -0,0 +1,91 @@
+<!-- last_verified: 2026-06-23 -->
+# genblaze-assemblyai
+
+[AssemblyAI](https://www.assemblyai.com/) **speech-to-text / transcription**
+provider adapter for [genblaze](https://github.com/backblaze-labs/genblaze).
+
+This connector is the inverse of every other genblaze adapter: instead of
+*generating* media it *consumes* an audio URL and *produces* a text
+transcript with word-level timings. The transcript lands as a hash-verified
+**TEXT asset** with a provenance manifest, so it composes into pipelines
+(generate audio → transcribe, caption a generated video) and persists to
+Backblaze B2 / S3 like any other genblaze step.
+
+## Install
+
+```bash
+pip install genblaze-assemblyai      # or: pip install "genblaze[assemblyai]"
+export ASSEMBLYAI_API_KEY="..."      # from https://www.assemblyai.com/app/api-keys
+```
+
+## Usage
+
+```python
+from genblaze_core import Modality, Pipeline
+from genblaze_assemblyai import AssemblyAIProvider
+
+run, manifest = (
+    Pipeline("transcribe")
+    .step(
+        AssemblyAIProvider(),
+        model="universal-3-pro",                       # speech_models: universal-3-pro | universal-2
+        prompt="https://example.com/podcast-episode.mp3",  # or params={"audio_url": ...}, or a chained audio input
+        modality=Modality.TEXT,
+        speaker_labels=True,                           # any TranscriptionConfig flag passes through
+    )
+    .run()
+)
+
+asset = run.steps[0].assets[0]
+print(asset.metadata["text"])          # the transcript
+print(asset.audio.word_timings[:3])    # [WordTiming(word=..., start=..., end=...), ...] (seconds)
+print(manifest.canonical_hash)
+```
+
+The audio URL is resolved from (in priority order) `step.inputs[0].url` →
+`step.params["audio_url"]` → `step.prompt`, then SSRF-validated (https:// or
+file:// only) before submission. `step.model` selects the AssemblyAI speech
+model (sent on the SDK's plural `speech_models` field — the live API retired
+the singular `speech_model` field and the `best` / `nano` aliases; current
+values are `universal-3-pro` / `universal-2`); every other
+`TranscriptionConfig` flag (`speaker_labels`, `language_code`,
+audio-intelligence options, …) passes through `step.params`.
+
+## Pricing
+
+The SDK ships no hardcoded prices. AssemblyAI bills per minute of *input*
+audio; the connector captures the input duration in
+`step.provider_payload["audio_duration"]` (seconds) during `fetch_output`.
+Register a recipe at runtime — see
+[`docs/reference/pricing-recipes.md`](https://github.com/backblaze-labs/genblaze/blob/main/docs/reference/pricing-recipes.md)
+("AssemblyAI" section):
+
+```python
+from genblaze_core.providers import per_response_metric
+
+RATE_PER_MINUTE = RATE  # replace RATE with the per-minute USD rate from assemblyai.com/pricing
+
+
+def per_minute(ctx):
+    seconds = ctx.provider_payload.get("audio_duration")
+    return (seconds / 60.0) * RATE_PER_MINUTE if seconds is not None else None
+
+
+provider = AssemblyAIProvider(api_key="...")
+# Speech-model slugs match the connector's family, so register against the
+# concrete slug(s) you use (register_pricing layers onto the family spec).
+for slug in ("universal-3-pro", "universal-2"):
+    provider.models.register_pricing(slug, per_response_metric(per_minute))
+```
+
+## Notes
+
+- **Out of scope for v1:** real-time/streaming transcription, LeMUR
+  (LLM-over-transcript), and first-class SRT/VTT subtitle outputs. Audio-
+  intelligence flags pass through to the API and land in `metadata`.
+
+## Docs
+
+- [AssemblyAI docs](https://www.assemblyai.com/docs)
+- [Transcript API reference](https://www.assemblyai.com/docs/api-reference/transcripts/get)
+- genblaze [new-provider guide](https://github.com/backblaze-labs/genblaze/blob/main/docs/guides/new-provider.md)

genblaze_assemblyai-0.3.0/genblaze_assemblyai/__init__.py

@@ -0,0 +1,7 @@
+"""AssemblyAI (speech-to-text / transcription) provider adapter for genblaze."""
+
+from genblaze_assemblyai.provider import AssemblyAIProvider
+
+from ._version import __version__  # noqa: F401 — re-exported
+
+__all__ = ["AssemblyAIProvider"]

genblaze_assemblyai-0.3.0/genblaze_assemblyai/_errors.py

@@ -0,0 +1,29 @@
+"""Shared AssemblyAI error mapping — used by provider.py.
+
+The AssemblyAI Python SDK raises exceptions that may carry an HTTP
+``status_code`` attribute (e.g. ``aai.types.TranscriptError`` and the
+underlying transport errors). We classify off the status code when present,
+then fall back to the shared string-based classifier. The same function also
+classifies the plain ``transcript.error`` string returned when a transcript
+finishes with ``status == "error"``.
+"""
+
+from genblaze_core.models.enums import ProviderErrorCode
+from genblaze_core.providers.base import classify_api_error
+
+
+def map_assemblyai_error(exc: Exception | str) -> ProviderErrorCode:
+    """Map an AssemblyAI API exception (or error string) to a ProviderErrorCode."""
+    status = getattr(exc, "status_code", None)
+    if isinstance(status, int):
+        if status == 429:
+            return ProviderErrorCode.RATE_LIMIT
+        if status in (401, 403):
+            return ProviderErrorCode.AUTH_FAILURE
+        if status in (400, 422):
+            return ProviderErrorCode.INVALID_INPUT
+        if status >= 500:
+            return ProviderErrorCode.SERVER_ERROR
+    # Fall back to shared string-based classifier (also handles the plain
+    # ``transcript.error`` string from a failed transcript).
+    return classify_api_error(exc)

genblaze_assemblyai-0.3.0/genblaze_assemblyai/_version.py

@@ -0,0 +1,14 @@
+"""``genblaze-assemblyai`` package version — single source of truth via importlib.metadata.
+
+Reading from ``importlib.metadata`` keeps the constant equal to whatever
+wheel is installed; no manual edits per release.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("genblaze-assemblyai")
+except PackageNotFoundError:  # pragma: no cover — editable dev installs
+    __version__ = "0.0.0+unknown"

genblaze_assemblyai-0.3.0/genblaze_assemblyai/provider.py

@@ -0,0 +1,409 @@
+"""AssemblyAIProvider — adapter for the AssemblyAI speech-to-text API.
+
+AssemblyAI is the inverse of every other genblaze connector: it *consumes* an
+audio URL and *produces* a text transcript (plus word-level timing, speaker
+labels, and optional audio-intelligence). It fits genblaze's primitives with
+zero core changes — the transcript lands as a **TEXT ``Asset``** following the
+``NvidiaChatProvider`` precedent (``url="text:{sha256}"``,
+``media_type="text/plain"``, payload in ``metadata["text"]``, sha256 over the
+text bytes), and word timings populate ``AudioMetadata.word_timings``.
+
+**API style:** genuinely async — the SDK's ``Transcriber().submit()`` is
+non-blocking (returns a queued ``Transcript`` immediately) and
+``aai.Transcript.get_by_id(id)`` polls/fetches by id. So this is a
+``BaseProvider`` (submit / poll / fetch_output), which gets adaptive polling,
+progress events, ``resume()`` crash-recovery, and poll caching for free.
+
+**Catalog architecture (genblaze-core 0.3.0):** AssemblyAI exposes no live
+``GET /models`` catalog; the model set is small and stable. This connector
+therefore declares ``DiscoverySupport.NONE`` and ships a single pattern-keyed
+``ModelFamily`` for the current ``universal-*`` speech models
+(``universal-3-pro`` / ``universal-2``) plus a permissive TEXT fallback so any
+slug passes through. ``step.model`` is the AssemblyAI speech model and is sent
+on the SDK's plural ``speech_models`` field — the live API has deprecated the
+singular ``speech_model`` field (and the legacy ``best`` / ``nano`` aliases).
+
+**Pricing:** AssemblyAI bills per minute of *input* audio. The SDK ships zero
+hardcoded prices — register a recipe at runtime that reads
+``step.provider_payload["audio_duration"]`` (seconds, captured during
+``fetch_output``); see ``docs/reference/pricing-recipes.md`` ("AssemblyAI").
+
+Docs: https://www.assemblyai.com/docs
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+from typing import Any
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+from genblaze_core.exceptions import ProviderError
+from genblaze_core.models.asset import Asset, AudioMetadata, WordTiming
+from genblaze_core.models.enums import Modality, ProviderErrorCode
+from genblaze_core.models.step import Step
+from genblaze_core.providers import (
+    BaseProvider,
+    DiscoverySupport,
+    ModelFamily,
+    ModelRegistry,
+    ModelSpec,
+    ProviderCapabilities,
+    RetryPolicy,
+    validate_chain_input_url,
+)
+from genblaze_core.providers.retry import retry_after_from_response
+from genblaze_core.runnable.config import RunnableConfig
+
+from ._errors import map_assemblyai_error
+
+logger = logging.getLogger("genblaze.assemblyai")
+
+# Terminal transcript statuses. AssemblyAI's lifecycle is
+# queued → processing → completed | error.
+_TERMINAL_STATUSES = frozenset({"completed", "error"})
+
+# The AssemblyAI speech-model family covers the current ``universal-*`` line
+# (``universal-3-pro``, ``universal-2``) — the only values the live API accepts
+# on the ``speech_models`` field as of 2026-06. The legacy ``speech_model``
+# tier aliases (``best`` / ``nano``) and the bare ``universal`` slug are now
+# rejected server-side; they fall through to the permissive fallback (which
+# still lets the request through — failures surface at submit, per NONE
+# discovery). Output is always a TEXT transcript, so the spec modality is TEXT.
+# spec_template.pricing MUST be None (pricing is user-registered).
+_ASSEMBLYAI_SPEECH_FAMILY = ModelFamily(
+    name="assemblyai-speech",
+    pattern=re.compile(r"^universal"),
+    spec_template=ModelSpec(model_id="*", modality=Modality.TEXT),
+    description="AssemblyAI speech models — universal-3-pro / universal-2.",
+    example_slugs=("universal-3-pro", "universal-2"),
+)
+
+_ASSEMBLYAI_FALLBACK = ModelSpec(model_id="*", modality=Modality.TEXT)
+
+
+def _ms_to_s(value: Any) -> float | None:
+    """Convert an AssemblyAI millisecond timestamp to seconds, or None."""
+    if value is None:
+        return None
+    try:
+        return float(value) / 1000.0
+    except (TypeError, ValueError):
+        return None
+
+
+def _status_str(transcript: Any) -> str:
+    """Return the transcript status as a lowercase string.
+
+    ``transcript.status`` is an ``aai.TranscriptStatus`` (a ``str`` enum) on
+    the real SDK; tests may use a plain string. Normalize both to the bare
+    value (``"completed"`` / ``"error"`` / …).
+    """
+    status = getattr(transcript, "status", None)
+    value = getattr(status, "value", None)
+    return str(value if value is not None else status).lower()
+
+
+def _audio_ref_for_sdk(audio_url: str) -> str:
+    """Shape a resolved audio URL into the form ``Transcriber.submit()`` wants.
+
+    The AssemblyAI SDK treats any non-HTTP string as a *local file path* and
+    opens it with ``open(ref, "rb")``. A ``file://`` URI — the form chained
+    SyncProvider outputs take, percent-encoded via ``quote()`` — would be
+    opened literally as the filename ``file:///tmp/a.wav`` and fail. Convert
+    validated ``file://`` URIs to a real filesystem path (``url2pathname``
+    handles percent-decoding and platform path conversion); pass ``https://``
+    URLs through untouched so the SDK fetches them remotely.
+
+    Assumes the URL already passed ``validate_chain_input_url`` (so the scheme
+    is ``https`` or ``file`` and any ``file://`` netloc is empty/``localhost``).
+    """
+    parsed = urlparse(audio_url)
+    if parsed.scheme == "file":
+        return url2pathname(parsed.path)
+    return audio_url
+
+
+def _serialize_utterances(utterances: Any) -> list[dict[str, Any]]:
+    """Flatten SDK utterance objects to canonical-JSON-safe dicts.
+
+    Times are converted ms → seconds to match ``word_timings``. Kept minimal
+    (speaker / text / start / end / confidence) — utterances are pass-through
+    context in ``metadata``, not a first-class shape in v1.
+    """
+    out: list[dict[str, Any]] = []
+    for u in utterances or []:
+        out.append(
+            {
+                "speaker": getattr(u, "speaker", None),
+                "text": getattr(u, "text", None),
+                "start": _ms_to_s(getattr(u, "start", None)),
+                "end": _ms_to_s(getattr(u, "end", None)),
+                "confidence": getattr(u, "confidence", None),
+            }
+        )
+    return out
+
+
+class AssemblyAIProvider(BaseProvider):
+    """Provider adapter for AssemblyAI speech-to-text transcription.
+
+    Transcribes an audio URL into a hash-verified TEXT asset with word-level
+    timings. The audio URL is resolved from (in priority order)
+    ``step.inputs[0].url`` → ``step.params["audio_url"]`` → ``step.prompt`` and
+    SSRF-validated via ``validate_chain_input_url`` before submission, so the
+    same provider works both standalone and chained into a pipeline (e.g.
+    generate audio → transcribe).
+
+    ``step.model`` is the AssemblyAI speech model (``universal-3-pro`` /
+    ``universal-2``) and is sent on the SDK's plural ``speech_models`` field;
+    any other ``TranscriptionConfig`` kwarg (``speaker_labels``,
+    ``language_code``, audio-intelligence flags, …) passes through
+    ``step.params``.
+
+    Args:
+        api_key: AssemblyAI API key. Falls back to ``ASSEMBLYAI_API_KEY``.
+        poll_interval: Base seconds between polls (the base class applies
+            adaptive backoff on top).
+        models: Optional custom ``ModelRegistry`` — overrides the class default.
+        retry_policy: Optional retry policy override.
+        probe_cache_ttl: Per-instance probe-cache TTL (no-op for NONE discovery
+            but accepted for API uniformity with other providers).
+        probe_cache_max_entries: Per-instance probe-cache size cap.
+    """
+
+    name = "assemblyai"
+    discovery_support = DiscoverySupport.NONE
+    """AssemblyAI exposes no ``GET /models`` catalog — the model set is small
+    and stable. Family-matched ``universal-*`` slugs (``universal-3-pro`` /
+    ``universal-2``) preflight as ``OK_PROVISIONAL``; everything else resolves
+    through the permissive fallback as ``UNKNOWN_PERMISSIVE``."""
+
+    @classmethod
+    def create_registry(cls) -> ModelRegistry:
+        return ModelRegistry(
+            provider_families=(_ASSEMBLYAI_SPEECH_FAMILY,),
+            fallback=_ASSEMBLYAI_FALLBACK,
+        )
+
+    def get_capabilities(self) -> ProviderCapabilities:
+        """AssemblyAI: audio in, TEXT transcript out."""
+        return ProviderCapabilities(
+            supported_modalities=[Modality.TEXT],
+            supported_inputs=["audio"],
+            accepts_chain_input=True,
+            models=self._models.known(),
+            output_formats=["text/plain"],
+        )
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        poll_interval: float = 3.0,
+        models: ModelRegistry | None = None,
+        retry_policy: RetryPolicy | None = None,
+        probe_cache_ttl: float | None = None,
+        probe_cache_max_entries: int | None = None,
+    ):
+        super().__init__(
+            models=models,
+            retry_policy=retry_policy,
+            probe_cache_ttl=probe_cache_ttl,
+            probe_cache_max_entries=probe_cache_max_entries,
+        )
+        self.poll_interval = poll_interval
+        self._api_key = api_key
+        self._client: Any = None
+
+    def _get_client(self) -> Any:
+        """Return the ``assemblyai`` module, configured with the API key.
+
+        AssemblyAI's SDK is module-scoped: transcription goes through
+        ``aai.Transcriber()`` / ``aai.Transcript.get_by_id()`` with the key set
+        on ``aai.settings.api_key``. So the "client" is the module itself. The
+        key is resolved here (the SDK does not auto-read ``ASSEMBLYAI_API_KEY``)
+        and a missing key fails fast with ``AUTH_FAILURE`` rather than a
+        deferred opaque 401.
+        """
+        if self._client is None:
+            key = self._api_key or os.getenv("ASSEMBLYAI_API_KEY")
+            if not key:
+                raise ProviderError(
+                    "No AssemblyAI API key found. Pass api_key=... or set ASSEMBLYAI_API_KEY.",
+                    error_code=ProviderErrorCode.AUTH_FAILURE,
+                )
+            try:
+                import assemblyai as aai
+            except ImportError as exc:
+                raise ProviderError(
+                    "assemblyai package not installed. Run: pip install assemblyai"
+                ) from exc
+            aai.settings.api_key = key
+            self._client = aai
+        return self._client
+
+    def normalize_params(
+        self, params: dict[str, Any], modality: Modality | None = None
+    ) -> dict[str, Any]:
+        """Map standard names to AssemblyAI's native ``TranscriptionConfig`` keys.
+
+        ``language`` → ``language_code`` (AssemblyAI native). Everything else
+        passes through untouched. Idempotent via the ``if x in p and native
+        not in p`` guard.
+        """
+        p = dict(params)
+        if "language" in p and "language_code" not in p:
+            p["language_code"] = p.pop("language")
+        return p
+
+    def _resolve_audio_url(self, step: Step) -> str:
+        """Resolve + SSRF-validate the audio URL to transcribe.
+
+        Priority: ``step.inputs[0].url`` (chained pipeline output) →
+        ``step.params["audio_url"]`` → ``step.prompt`` (standalone use). The
+        chosen URL is validated with ``validate_chain_input_url`` (https:// or
+        file:// only) before it leaves the process.
+        """
+        if step.inputs and step.inputs[0].url:
+            url = step.inputs[0].url
+        elif step.params.get("audio_url"):
+            url = str(step.params["audio_url"])
+        elif step.prompt:
+            url = step.prompt
+        else:
+            raise ProviderError(
+                "AssemblyAI requires an audio URL via step.inputs[0], "
+                "step.params['audio_url'], or step.prompt.",
+                error_code=ProviderErrorCode.INVALID_INPUT,
+            )
+        validate_chain_input_url(url)
+        return url
+
+    def submit(self, step: Step, config: RunnableConfig | None = None) -> Any:
+        """Submit a transcription job (non-blocking) and return its id."""
+        aai = self._get_client()
+        # Resolve + SSRF-validate, then shape for the SDK: a validated file://
+        # chain input must reach Transcriber.submit() as a local filesystem
+        # path, since the SDK open()s any non-HTTP string literally.
+        audio_ref = _audio_ref_for_sdk(self._resolve_audio_url(step))
+        try:
+            cfg_kwargs = self.normalize_params(dict(step.params), step.modality)
+            # audio_url is the submit() argument, not a TranscriptionConfig field.
+            cfg_kwargs.pop("audio_url", None)
+            # step.model is the speech model. The live API has deprecated the
+            # singular ``speech_model`` field (and the legacy best/nano tier
+            # aliases); the slug is sent on the plural ``speech_models`` list,
+            # which currently accepts ``universal-3-pro`` / ``universal-2``.
+            if step.model:
+                cfg_kwargs["speech_models"] = [step.model]
+            transcription_config = aai.TranscriptionConfig(**cfg_kwargs)
+            transcriber = aai.Transcriber()
+            transcript = transcriber.submit(audio_ref, config=transcription_config)
+            return transcript.id
+        except ProviderError:
+            raise
+        except Exception as exc:
+            raise ProviderError(
+                f"AssemblyAI submit failed: {exc}",
+                error_code=map_assemblyai_error(exc),
+                retry_after=retry_after_from_response(exc),
+            ) from exc
+
+    def poll(self, prediction_id: Any, config: RunnableConfig | None = None) -> bool:
+        """Return True once the transcript reaches a terminal status."""
+        aai = self._get_client()
+        try:
+            transcript = aai.Transcript.get_by_id(prediction_id)
+            if _status_str(transcript) in _TERMINAL_STATUSES:
+                self._cache_poll_result(prediction_id, transcript)
+                return True
+            return False
+        except ProviderError:
+            raise
+        except Exception as exc:
+            raise ProviderError(
+                f"AssemblyAI poll failed: {exc}",
+                error_code=map_assemblyai_error(exc),
+                retry_after=retry_after_from_response(exc),
+            ) from exc
+
+    def fetch_output(self, prediction_id: Any, step: Step) -> Step:
+        """Build the TEXT transcript asset from the completed transcript."""
+        aai = self._get_client()
+        try:
+            transcript = self._get_cached_poll_result(prediction_id)
+            if transcript is None:
+                transcript = aai.Transcript.get_by_id(prediction_id)
+
+            status = _status_str(transcript)
+            if status == "error":
+                err = getattr(transcript, "error", None) or "AssemblyAI transcription failed"
+                raise ProviderError(str(err), error_code=map_assemblyai_error(err))
+            if status != "completed":
+                # fetch_output is only reached after poll() confirms a terminal
+                # status, so this guards the off-happy-path / resume case rather
+                # than silently emitting an empty transcript for a running job.
+                raise ProviderError(
+                    f"AssemblyAI transcript {prediction_id} is not complete (status={status!r}).",
+                    error_code=ProviderErrorCode.SERVER_ERROR,
+                )
+
+            text = getattr(transcript, "text", None) or ""
+            text_bytes = text.encode("utf-8")
+            digest = hashlib.sha256(text_bytes).hexdigest()
+
+            asset = Asset(
+                url=f"text:{digest}",  # synthetic TEXT asset (NvidiaChatProvider precedent)
+                media_type="text/plain",
+                sha256=digest,
+                size_bytes=len(text_bytes),
+            )
+
+            words = getattr(transcript, "words", None)
+            if words:
+                # AssemblyAI word start/end are in MILLISECONDS; WordTiming
+                # expects seconds — divide by 1000.
+                timings = [
+                    WordTiming(
+                        word=getattr(w, "text", "") or "",
+                        start=_ms_to_s(getattr(w, "start", None)) or 0.0,
+                        end=_ms_to_s(getattr(w, "end", None)) or 0.0,
+                        confidence=getattr(w, "confidence", None),
+                    )
+                    for w in words
+                ]
+                asset.audio = AudioMetadata(word_timings=timings)
+
+            asset.metadata["text"] = text
+            language = getattr(transcript, "language_code", None)
+            if language is not None:
+                asset.metadata["language"] = language
+            confidence = getattr(transcript, "confidence", None)
+            if confidence is not None:
+                asset.metadata["confidence"] = confidence
+            utterances = getattr(transcript, "utterances", None)
+            if utterances:
+                asset.metadata["utterances"] = _serialize_utterances(utterances)
+
+            step.assets = [asset]
+
+            # Seconds of input audio; the pricing recipe reads this.
+            audio_duration = getattr(transcript, "audio_duration", None)
+            if audio_duration is not None:
+                step.provider_payload["audio_duration"] = audio_duration
+                asset.metadata["audio_duration"] = audio_duration
+
+            self._apply_registry_pricing(step)
+            return step
+        except ProviderError:
+            raise
+        except Exception as exc:
+            raise ProviderError(
+                f"AssemblyAI fetch_output failed: {exc}",
+                error_code=map_assemblyai_error(exc),
+                retry_after=retry_after_from_response(exc),
+            ) from exc

genblaze_assemblyai-0.3.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "genblaze-assemblyai"
+version = "0.3.0"
+description = "AssemblyAI (speech-to-text / transcription) provider adapter for genblaze"
+authors = [{name = "Eduardo Pavez", email = "epavez@backblaze.com"}]
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia",
+    "Topic :: Software Development :: Libraries",
+]
+keywords = ["genblaze", "ai", "media", "manifest", "provenance", "c2pa-ready", "genai", "pipeline", "assemblyai", "speech-to-text", "transcription", "audio"]
+
+dependencies = [
+    "genblaze-core>=0.3.0,<0.4",
+    # The provider uses Transcriber().submit() (non-blocking) and
+    # aai.Transcript.get_by_id(id) for polling; both have been stable across
+    # the 0.x line. The floor is 0.45, not 0.40: submit() always sends the
+    # speech model on TranscriptionConfig's plural ``speech_models`` field,
+    # which the SDK only added in 0.45.0 — 0.40.0–0.44.3 raise
+    # ``TypeError: ... unexpected keyword argument 'speech_models'`` before the
+    # request ever leaves the process. Bounded below 1.0 so a future major
+    # can't silently reshape these call sites.
+    "assemblyai>=0.45,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/backblaze-labs/genblaze"
+Documentation = "https://github.com/backblaze-labs/genblaze"
+Repository = "https://github.com/backblaze-labs/genblaze"
+Issues = "https://github.com/backblaze-labs/genblaze/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.entry-points."genblaze.providers"]
+assemblyai = "genblaze_assemblyai:AssemblyAIProvider"
+
+[tool.hatch.build.targets.wheel]
+packages = ["genblaze_assemblyai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.deptry]
+# Treat the `dev` extra as dev-only tooling so deptry does not flag pytest
+# (and other test-only deps) as unused declared deps (DEP002).
+optional_dependencies_dev_groups = ["dev"]

genblaze_assemblyai-0.3.0/tests/test_assemblyai.py

@@ -0,0 +1,527 @@
+"""Tests for AssemblyAIProvider (mocked — no real API calls).
+
+The provider's "client" is the ``assemblyai`` module itself (transcription
+goes through ``aai.Transcriber()`` / ``aai.Transcript.get_by_id()`` with the
+key on ``aai.settings.api_key``). Tests inject a fake module via
+``provider._client`` — the lazy ``import assemblyai`` in ``_get_client`` is
+never reached on the happy path, so the real SDK is not required.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+from genblaze_core.exceptions import ProviderError
+from genblaze_core.models.asset import Asset
+from genblaze_core.models.enums import Modality, ProviderErrorCode, StepStatus
+from genblaze_core.models.step import Step
+from genblaze_core.testing import ProviderComplianceTests
+
+AUDIO_URL = "https://example.com/audio.mp3"
+
+
+# --- fakes ----------------------------------------------------------------
+
+
+class _FakeWord:
+    def __init__(self, text: str, start: int, end: int, confidence: float = 0.99):
+        self.text = text
+        self.start = start  # milliseconds (AssemblyAI native)
+        self.end = end  # milliseconds
+        self.confidence = confidence
+
+
+def _fake_transcript(
+    *,
+    status: str = "completed",
+    text: str = "hello world",
+    with_words: bool = True,
+    audio_duration: float | None = 12.5,
+    error: str | None = None,
+    language_code: str | None = "en_us",
+    confidence: float | None = 0.97,
+    utterances=None,
+):
+    words = (
+        [_FakeWord("hello", 0, 500, 0.99), _FakeWord("world", 500, 1000, 0.98)]
+        if with_words
+        else None
+    )
+    return SimpleNamespace(
+        id="transcript-abc123",
+        status=status,
+        text=text,
+        words=words,
+        audio_duration=audio_duration,
+        language_code=language_code,
+        confidence=confidence,
+        utterances=utterances,
+        error=error,
+    )
+
+
+class _FakeTranscriber:
+    """Records the submitted (audio_url, config) and returns a queued id."""
+
+    last_submit: dict = {}
+
+    def submit(self, audio_url, config=None):
+        _FakeTranscriber.last_submit = {"audio_url": audio_url, "config": config}
+        return SimpleNamespace(id="transcript-abc123", status="queued")
+
+
+def _make_fake_aai(transcript=None):
+    """Build a fake ``assemblyai`` module exposing the surface the provider uses."""
+    transcript = transcript if transcript is not None else _fake_transcript()
+    fake = SimpleNamespace()
+    fake.settings = SimpleNamespace(api_key=None)
+    fake.Transcriber = _FakeTranscriber
+    fake.Transcript = SimpleNamespace(get_by_id=lambda tid: transcript)
+    fake.TranscriptionConfig = lambda **kwargs: SimpleNamespace(**kwargs)
+    return fake
+
+
+def _make_provider(transcript=None):
+    from genblaze_assemblyai import AssemblyAIProvider
+
+    provider = AssemblyAIProvider(api_key="test-key", poll_interval=0.0)
+    provider._client = _make_fake_aai(transcript)
+    return provider
+
+
+def _make_step(**kwargs) -> Step:
+    kwargs.setdefault("provider", "assemblyai")
+    kwargs.setdefault("model", "universal-3-pro")
+    kwargs.setdefault("modality", Modality.TEXT)
+    kwargs.setdefault("prompt", AUDIO_URL)
+    return Step(**kwargs)
+
+
+@pytest.fixture(autouse=True)
+def _reset_registry_cache():
+    """Isolate the class-level model registry between tests.
+
+    ``BaseProvider`` caches one ``ModelRegistry`` per provider class
+    (``models_default()``), shared across instances. A test that calls
+    ``register_pricing`` would otherwise leak the user-registered spec — and
+    flip a family-matched slug's validation outcome to AUTHORITATIVE — into
+    later tests. Resetting the cache gives each test a fresh registry built
+    from the (unmutated) module-level family/fallback specs.
+    """
+    from genblaze_assemblyai import AssemblyAIProvider
+
+    AssemblyAIProvider._models_cache = None
+    yield
+    AssemblyAIProvider._models_cache = None
+
+
+# --- submit ---------------------------------------------------------------
+
+
+def test_submit_returns_id_and_forwards_audio_url():
+    provider = _make_provider()
+    step = _make_step()
+    pred_id = provider.submit(step)
+    assert pred_id == "transcript-abc123"
+    assert _FakeTranscriber.last_submit["audio_url"] == AUDIO_URL
+
+
+def test_submit_passes_speech_model_to_config():
+    provider = _make_provider()
+    step = _make_step(model="universal-3-pro")
+    provider.submit(step)
+    cfg = _FakeTranscriber.last_submit["config"]
+    # step.model is sent on the plural ``speech_models`` field — the live API
+    # deprecated the singular ``speech_model`` field and the best/nano aliases.
+    assert cfg.speech_models == ["universal-3-pro"]
+
+
+def test_submit_strips_audio_url_from_config():
+    provider = _make_provider()
+    step = _make_step(prompt=None, params={"audio_url": AUDIO_URL, "speaker_labels": True})
+    provider.submit(step)
+    cfg = _FakeTranscriber.last_submit["config"]
+    assert not hasattr(cfg, "audio_url")
+    assert cfg.speaker_labels is True
+
+
+def test_submit_converts_file_uri_to_local_path():
+    # A validated file:// chain input (e.g. a generate-audio step's output)
+    # must reach the SDK as a local filesystem PATH — the SDK open()s any
+    # non-HTTP string literally, so forwarding "file:///tmp/clip.wav" would try
+    # to open that exact filename and fail.
+    provider = _make_provider()
+    step = _make_step(prompt="file:///srv/audio/clip.wav")
+    provider.submit(step)
+    assert _FakeTranscriber.last_submit["audio_url"] == "/srv/audio/clip.wav"
+
+
+def test_submit_decodes_percent_encoded_file_uri():
+    # Sibling connectors emit file:// URLs via quote(), so a path with spaces
+    # arrives percent-encoded; it must be decoded back to the real path.
+    provider = _make_provider()
+    step = _make_step(prompt="file:///srv/audio/my%20clip.wav")
+    provider.submit(step)
+    assert _FakeTranscriber.last_submit["audio_url"] == "/srv/audio/my clip.wav"
+
+
+def test_submit_file_uri_localhost_netloc_to_local_path():
+    # RFC 8089 'file://localhost/...' (allowed by validate_chain_input_url)
+    # drops the localhost host and resolves to the bare path.
+    provider = _make_provider()
+    step = _make_step(prompt="file://localhost/srv/audio/clip.wav")
+    provider.submit(step)
+    assert _FakeTranscriber.last_submit["audio_url"] == "/srv/audio/clip.wav"
+
+
+def test_submit_https_url_passes_through_unchanged():
+    # https:// inputs are uploaded/fetched remotely by the SDK — not opened
+    # locally — so they must reach submit() byte-for-byte unchanged.
+    provider = _make_provider()
+    step = _make_step(prompt=AUDIO_URL)
+    provider.submit(step)
+    assert _FakeTranscriber.last_submit["audio_url"] == AUDIO_URL
+
+
+# --- full lifecycle -------------------------------------------------------
+
+
+def test_full_lifecycle_via_invoke():
+    provider = _make_provider()
+    step = _make_step()
+    result = provider.invoke(step)
+    assert result.status == StepStatus.SUCCEEDED
+    assert len(result.assets) == 1
+    asset = result.assets[0]
+    assert asset.media_type == "text/plain"
+    assert asset.url.startswith("text:")
+    assert asset.metadata["text"] == "hello world"
+
+
+def test_text_asset_hash_matches_content():
+    provider = _make_provider()
+    step = _make_step()
+    pred_id = provider.submit(step)
+    result = provider.fetch_output(pred_id, step)
+    asset = result.assets[0]
+    expected = hashlib.sha256(b"hello world").hexdigest()
+    assert asset.sha256 == expected
+    assert asset.url == f"text:{expected}"
+    assert asset.size_bytes == len(b"hello world")
+
+
+# --- word timings (ms -> seconds) ----------------------------------------
+
+
+def test_word_timings_converted_ms_to_seconds():
+    provider = _make_provider()
+    step = _make_step()
+    pred_id = provider.submit(step)
+    result = provider.fetch_output(pred_id, step)
+    timings = result.assets[0].audio.word_timings
+    assert [t.word for t in timings] == ["hello", "world"]
+    # 0 ms -> 0.0 s, 500 ms -> 0.5 s, 1000 ms -> 1.0 s
+    assert timings[0].start == 0.0
+    assert timings[0].end == 0.5
+    assert timings[1].start == 0.5
+    assert timings[1].end == 1.0
+    assert timings[1].confidence == 0.98
+
+
+def test_no_words_leaves_audio_metadata_unset():
+    provider = _make_provider(_fake_transcript(with_words=False))
+    step = _make_step()
+    pred_id = provider.submit(step)
+    result = provider.fetch_output(pred_id, step)
+    assert result.assets[0].audio is None
+
+
+# --- audio_duration / pricing payload ------------------------------------
+
+
+def test_audio_duration_captured_in_provider_payload():
+    provider = _make_provider(_fake_transcript(audio_duration=42.0))
+    step = _make_step()
+    pred_id = provider.submit(step)
+    result = provider.fetch_output(pred_id, step)
+    assert result.provider_payload["audio_duration"] == 42.0
+    assert result.assets[0].metadata["audio_duration"] == 42.0
+
+
+def test_user_registered_per_minute_pricing():
+    from genblaze_core.providers import per_response_metric
+
+    provider = _make_provider(_fake_transcript(audio_duration=120.0))  # 2 minutes
+
+    def per_minute(ctx):
+        dur = ctx.provider_payload.get("audio_duration")
+        return (dur / 60.0) * 0.12 if dur is not None else None
+
+    # "universal-3-pro" matches the speech family, so register against the
+    # concrete slug (register_pricing falls through to the family spec and
+    # layers pricing).
+    provider.models.register_pricing("universal-3-pro", per_response_metric(per_minute))
+    step = _make_step(model="universal-3-pro")
+    result = provider.invoke(step)
+    assert result.cost_usd == pytest.approx(2 * 0.12)
+
+
+# --- audio-url resolution precedence -------------------------------------
+
+
+def test_audio_url_precedence_inputs_first():
+    provider = _make_provider()
+    step = _make_step(
+        prompt="https://prompt.example/p.mp3",
+        params={"audio_url": "https://params.example/p.mp3"},
+        inputs=[Asset(url="https://inputs.example/in.mp3", media_type="audio/mpeg")],
+    )
+    assert provider._resolve_audio_url(step) == "https://inputs.example/in.mp3"
+
+
+def test_audio_url_precedence_params_over_prompt():
+    provider = _make_provider()
+    step = _make_step(
+        prompt="https://prompt.example/p.mp3",
+        params={"audio_url": "https://params.example/p.mp3"},
+    )
+    assert provider._resolve_audio_url(step) == "https://params.example/p.mp3"
+
+
+def test_audio_url_falls_back_to_prompt():
+    provider = _make_provider()
+    step = _make_step(prompt="https://prompt.example/p.mp3")
+    assert provider._resolve_audio_url(step) == "https://prompt.example/p.mp3"
+
+
+def test_empty_input_url_falls_through_to_params():
+    # An input asset with an empty url must not short-circuit the precedence
+    # chain — it degrades to params["audio_url"] rather than failing the SSRF
+    # validator on "".
+    provider = _make_provider()
+    step = _make_step(
+        prompt=None,
+        params={"audio_url": "https://params.example/p.mp3"},
+        inputs=[Asset(url="", media_type="audio/mpeg")],
+    )
+    assert provider._resolve_audio_url(step) == "https://params.example/p.mp3"
+
+
+def test_missing_audio_url_raises_invalid_input():
+    provider = _make_provider()
+    step = _make_step(prompt=None)
+    with pytest.raises(ProviderError) as ei:
+        provider.submit(step)
+    assert ei.value.error_code == ProviderErrorCode.INVALID_INPUT
+
+
+def test_unsafe_audio_url_rejected():
+    provider = _make_provider()
+    step = _make_step(prompt="http://insecure.example/a.mp3")
+    with pytest.raises(ProviderError):
+        provider.submit(step)
+
+
+# --- error status ---------------------------------------------------------
+
+
+def test_error_status_raises_provider_error():
+    provider = _make_provider(_fake_transcript(status="error", error="bad audio file"))
+    step = _make_step()
+    pred_id = provider.submit(step)
+    with pytest.raises(ProviderError, match="bad audio file"):
+        provider.fetch_output(pred_id, step)
+
+
+def test_poll_false_until_terminal():
+    provider = _make_provider(_fake_transcript(status="processing"))
+    step = _make_step()
+    pred_id = provider.submit(step)
+    assert provider.poll(pred_id) is False
+
+
+def test_fetch_output_non_terminal_raises():
+    # Defensive guard: fetch_output on a still-running transcript must raise
+    # rather than emit a silently-empty (text:"") asset and report SUCCEEDED.
+    provider = _make_provider(_fake_transcript(status="processing", text=None))
+    step = _make_step()
+    pred_id = provider.submit(step)
+    with pytest.raises(ProviderError, match="not complete") as ei:
+        provider.fetch_output(pred_id, step)
+    assert ei.value.error_code == ProviderErrorCode.SERVER_ERROR
+
+
+def test_submit_api_error_wrapped_with_code():
+    from genblaze_assemblyai import AssemblyAIProvider
+
+    class _RaisingTranscriber:
+        def submit(self, audio_url, config=None):
+            err = RuntimeError("boom")
+            err.status_code = 429  # type: ignore[attr-defined]
+            raise err
+
+    fake = _make_fake_aai()
+    fake.Transcriber = _RaisingTranscriber
+    provider = AssemblyAIProvider(api_key="test-key", poll_interval=0.0)
+    provider._client = fake
+    step = _make_step()
+    with pytest.raises(ProviderError, match="AssemblyAI submit failed") as ei:
+        provider.submit(step)
+    assert ei.value.error_code == ProviderErrorCode.RATE_LIMIT
+
+
+# --- normalize_params -----------------------------------------------------
+
+
+def test_normalize_params_language_alias():
+    provider = _make_provider()
+    out = provider.normalize_params({"language": "es", "speaker_labels": True})
+    assert out["language_code"] == "es"
+    assert "language" not in out
+    assert out["speaker_labels"] is True
+
+
+def test_normalize_params_idempotent():
+    provider = _make_provider()
+    params = {"language": "es", "speaker_labels": True}
+    once = provider.normalize_params(params)
+    twice = provider.normalize_params(once)
+    assert once == twice
+
+
+def test_normalize_params_respects_existing_language_code():
+    provider = _make_provider()
+    out = provider.normalize_params({"language": "es", "language_code": "en_us"})
+    # Existing native key wins; the alias is left intact (idempotency guard).
+    assert out["language_code"] == "en_us"
+
+
+# --- credentials ----------------------------------------------------------
+
+
+def test_missing_api_key_raises_auth_failure(monkeypatch):
+    monkeypatch.delenv("ASSEMBLYAI_API_KEY", raising=False)
+    from genblaze_assemblyai import AssemblyAIProvider
+
+    provider = AssemblyAIProvider(api_key=None)  # no injected client
+    step = _make_step()
+    with pytest.raises(ProviderError, match="No AssemblyAI API key") as ei:
+        provider.submit(step)
+    assert ei.value.error_code == ProviderErrorCode.AUTH_FAILURE
+
+
+# --- error mapping --------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "status,expected",
+    [
+        (429, ProviderErrorCode.RATE_LIMIT),
+        (401, ProviderErrorCode.AUTH_FAILURE),
+        (403, ProviderErrorCode.AUTH_FAILURE),
+        (400, ProviderErrorCode.INVALID_INPUT),
+        (422, ProviderErrorCode.INVALID_INPUT),
+        (500, ProviderErrorCode.SERVER_ERROR),
+        (503, ProviderErrorCode.SERVER_ERROR),
+    ],
+)
+def test_map_assemblyai_error_status_codes(status, expected):
+    from genblaze_assemblyai._errors import map_assemblyai_error
+
+    exc = RuntimeError("err")
+    exc.status_code = status  # type: ignore[attr-defined]
+    assert map_assemblyai_error(exc) == expected
+
+
+def test_map_assemblyai_error_no_status_falls_back():
+    from genblaze_assemblyai._errors import map_assemblyai_error
+
+    assert map_assemblyai_error(RuntimeError("totally opaque")) == ProviderErrorCode.UNKNOWN
+
+
+def test_map_assemblyai_error_accepts_error_string():
+    from genblaze_assemblyai._errors import map_assemblyai_error
+
+    # transcript.error is a plain string; the classifier handles it.
+    assert map_assemblyai_error("rate limit exceeded") == ProviderErrorCode.RATE_LIMIT
+
+
+# --- catalog decoupling ---------------------------------------------------
+
+
+def test_declares_discovery_support_none():
+    from genblaze_assemblyai import AssemblyAIProvider
+    from genblaze_core.providers import DiscoverySupport
+
+    assert AssemblyAIProvider.discovery_support is DiscoverySupport.NONE
+
+
+@pytest.mark.parametrize("slug", ["universal", "universal-2", "universal-3-pro"])
+def test_speech_slug_matches_family(slug):
+    from genblaze_core.providers import ValidationOutcome
+
+    provider = _make_provider()
+    assert provider.validate_model(slug).outcome is ValidationOutcome.OK_PROVISIONAL
+
+
+def test_non_speech_slug_unknown_permissive():
+    from genblaze_core.providers import ValidationOutcome
+
+    provider = _make_provider()
+    assert provider.validate_model("some-other-model").outcome is (
+        ValidationOutcome.UNKNOWN_PERMISSIVE
+    )
+
+
+def test_family_and_fallback_carry_no_pricing():
+    provider = _make_provider()
+    assert provider._models.get("universal-3-pro").pricing is None  # family-matched
+    assert provider._models.get("anything-else").pricing is None  # permissive fallback
+
+
+def test_capabilities_text_only():
+    provider = _make_provider()
+    caps = provider.get_capabilities()
+    assert caps.supported_modalities == [Modality.TEXT]
+    assert caps.accepts_chain_input is True
+    assert caps.output_formats == ["text/plain"]
+
+
+# --- compliance harness ---------------------------------------------------
+
+
+class TestAssemblyAICompliance(ProviderComplianceTests):
+    """Verify AssemblyAIProvider satisfies the genblaze provider contract."""
+
+    # AssemblyAI ships zero hardcoded prices (per-minute-of-input-audio is
+    # user-registered; see docs/reference/pricing-recipes.md). cost_usd stays
+    # None unless the user registers a strategy — same posture as Hume.
+    expects_cost = False
+
+    @pytest.fixture(autouse=True)
+    def _patch_sdk(self):
+        # Safety net so the lazy ``import assemblyai`` resolves to the fake if
+        # ever reached; make_provider also injects ``_client`` directly.
+        with patch.dict(sys.modules, {"assemblyai": _make_fake_aai()}):
+            yield
+
+    def make_provider(self):
+        return _make_provider()
+
+    def make_step(self):
+        return _make_step()
+
+    def test_assets_have_valid_urls(self) -> None:
+        """Transcripts emit a synthetic ``text:{sha256}`` asset (the
+        NvidiaChatProvider TEXT-asset precedent), not an https:// / file://
+        URL — so we assert that scheme instead of the harness default."""
+        provider = self.make_provider()
+        step = self.make_step()
+        result = provider.invoke(step)
+        assert result.assets
+        for asset in result.assets:
+            assert asset.url.startswith("text:"), f"Expected text: asset URL, got {asset.url}"