genblaze-nvidia 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,19 @@
1
+ """NVIDIA NIM provider adapters for genblaze (video, image, audio, chat).
2
+
3
+ All four modalities share a single ``nvapi-`` key (``NVIDIA_API_KEY`` env var)
4
+ and a common HTTP layer. The three *Provider classes integrate with Pipelines
5
+ via entry points; the ``chat`` / ``achat`` helpers sit alongside for LLM calls.
6
+ """
7
+
8
+ from genblaze_nvidia.audio import NvidiaAudioProvider
9
+ from genblaze_nvidia.chat import achat, chat
10
+ from genblaze_nvidia.image import NvidiaImageProvider
11
+ from genblaze_nvidia.video import NvidiaVideoProvider
12
+
13
+ __all__ = [
14
+ "NvidiaVideoProvider",
15
+ "NvidiaImageProvider",
16
+ "NvidiaAudioProvider",
17
+ "chat",
18
+ "achat",
19
+ ]
@@ -0,0 +1,420 @@
1
+ """Shared HTTP + NVCF plumbing for all NVIDIA NIM providers.
2
+
3
+ NVIDIA exposes two public API surfaces on a single ``nvapi-`` key:
4
+
5
+ - ``integrate.api.nvidia.com/v1`` — OpenAI-compatible chat, embeddings,
6
+ reranking. Always synchronous.
7
+ - ``ai.api.nvidia.com/v1/genai/{vendor}/{slug}`` — image / video / audio
8
+ generation. Each endpoint may return either ``200`` with an inline payload
9
+ (small/fast models) or ``202 + NVCF-REQID`` header (async, polled via
10
+ ``api.nvcf.nvidia.com/v2/nvcf/pexec/status/{req_id}``).
11
+
12
+ This module owns the HTTP client, URL construction, and NVCF polling so the
13
+ per-modality provider classes only deal with payload shaping and response
14
+ parsing.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import base64
20
+ import binascii
21
+ import json
22
+ import os
23
+ import time
24
+ import uuid
25
+ from pathlib import Path
26
+
27
+ import httpx
28
+ from genblaze_core.exceptions import ProviderError
29
+ from genblaze_core.models.enums import ProviderErrorCode
30
+ from genblaze_core.providers.retry import retry_after_from_response
31
+
32
+ from ._errors import map_nvidia_error
33
+
34
+ # Two different public base URLs — don't collapse them. Chat hits the
35
+ # OpenAI-compatible surface; image/video/audio generation hits the model-
36
+ # specific genai surface.
37
+ DEFAULT_CHAT_BASE_URL = "https://integrate.api.nvidia.com/v1"
38
+ DEFAULT_GEN_BASE_URL = "https://ai.api.nvidia.com/v1"
39
+ DEFAULT_NVCF_STATUS_URL = "https://api.nvcf.nvidia.com/v2/nvcf/pexec/status"
40
+
41
+ # Env vars checked in order. NVIDIA_API_KEY is the documented primary;
42
+ # NVIDIA_NIM_API_KEY is a common alias some tutorials still recommend.
43
+ _API_KEY_ENV_VARS = ("NVIDIA_API_KEY", "NVIDIA_NIM_API_KEY")
44
+
45
+ # HTTP statuses that mean "job queued, poll NVCF".
46
+ _NVCF_PENDING_STATUSES = frozenset({202})
47
+ _NVCF_DONE_STATUSES = frozenset({200})
48
+
49
+
50
+ def resolve_api_key(api_key: str | None) -> str | None:
51
+ """Return the caller-supplied key, falling back to the documented env vars."""
52
+ if api_key:
53
+ return api_key
54
+ for name in _API_KEY_ENV_VARS:
55
+ value = os.environ.get(name)
56
+ if value:
57
+ return value
58
+ return None
59
+
60
+
61
+ def build_generation_path(model: str) -> str:
62
+ """Build the path component for ``ai.api.nvidia.com/v1/genai/{model}``.
63
+
64
+ NVIDIA's build.nvidia.com slugs are ``vendor/slug`` (e.g.
65
+ ``stabilityai/stable-diffusion-xl``, ``nvidia/cosmos-1.0-7b-diffusion-text2world``).
66
+ We construct the endpoint path as ``/genai/{model}`` — new models ship
67
+ usable via pass-through without a code change.
68
+ """
69
+ model = model.strip("/")
70
+ if not model:
71
+ raise ProviderError(
72
+ "Empty model id — cannot build NVIDIA generation URL",
73
+ error_code=ProviderErrorCode.INVALID_INPUT,
74
+ )
75
+ return f"/genai/{model}"
76
+
77
+
78
+ def decode_base64_payload(data: str, *, field: str = "base64") -> bytes:
79
+ """Decode a base64 string from an NVIDIA response, raising on bad data.
80
+
81
+ NIM returns image/video/audio outputs as base64 in either ``artifacts[*].base64``
82
+ or top-level ``image`` / ``video`` / ``audio`` keys depending on the model.
83
+ Pads the input to a multiple of 4 so endpoints that ship unpadded base64
84
+ still decode — we still ``validate=True`` to catch genuinely corrupt data.
85
+ """
86
+ # Accept URL-safe base64 too — some endpoints use '-'/'_' instead of '+'/'/'.
87
+ normalized = data.replace("-", "+").replace("_", "/")
88
+ padding = (-len(normalized)) % 4
89
+ try:
90
+ return base64.b64decode(normalized + "=" * padding, validate=True)
91
+ except (binascii.Error, ValueError) as exc:
92
+ raise ProviderError(
93
+ f"Failed to decode base64 {field!r} from NVIDIA response: {exc}",
94
+ error_code=ProviderErrorCode.SERVER_ERROR,
95
+ ) from exc
96
+
97
+
98
+ def extract_base64_assets(body: dict) -> list[tuple[bytes, str | None]]:
99
+ """Pull ``(bytes, optional_mime)`` tuples from an NVIDIA generation response.
100
+
101
+ Handles the shapes NIM currently emits:
102
+ - ``{"artifacts": [{"base64": "...", "mime_type": "image/png"}, ...]}`` — SDXL / FLUX / SD 3.5
103
+ - ``{"image": "..."}`` / ``{"video": "..."}`` / ``{"audio": "..."}`` — singleton convenience
104
+ - ``{"data": [{"b64_json": "..."}, ...]}`` — some newer endpoints mirror OpenAI image shape
105
+
106
+ Returns an empty list if no base64 payload is found — the caller decides
107
+ whether that's an error.
108
+ """
109
+ out: list[tuple[bytes, str | None]] = []
110
+
111
+ artifacts = body.get("artifacts")
112
+ if isinstance(artifacts, list):
113
+ for art in artifacts:
114
+ if not isinstance(art, dict):
115
+ continue
116
+ b64 = art.get("base64") or art.get("b64_json")
117
+ if isinstance(b64, str) and b64:
118
+ mime = art.get("mime_type") or art.get("mimeType")
119
+ out.append((decode_base64_payload(b64), mime if isinstance(mime, str) else None))
120
+ if out:
121
+ return out
122
+
123
+ data = body.get("data")
124
+ if isinstance(data, list):
125
+ for item in data:
126
+ if not isinstance(item, dict):
127
+ continue
128
+ b64 = item.get("b64_json") or item.get("base64")
129
+ if isinstance(b64, str) and b64:
130
+ out.append((decode_base64_payload(b64), None))
131
+ if out:
132
+ return out
133
+
134
+ # Singleton convenience keys — only check after the list-shaped forms so
135
+ # multi-output responses aren't lossily collapsed to the first entry.
136
+ for key, mime in (("image", None), ("video", None), ("audio", None)):
137
+ val = body.get(key)
138
+ if isinstance(val, str) and val:
139
+ out.append((decode_base64_payload(val, field=key), mime))
140
+ return out
141
+
142
+ return out
143
+
144
+
145
+ def extract_asset_urls(body: dict) -> list[str]:
146
+ """Pull hosted asset URLs from an NVIDIA response envelope, if any.
147
+
148
+ Some gated endpoints (Cosmos, Edify) upload outputs to NIM's CDN and return
149
+ signed URLs instead of inlining base64 — parse those too so callers don't
150
+ need to care which shape the model returned.
151
+ """
152
+ urls: list[str] = []
153
+ artifacts = body.get("artifacts")
154
+ if isinstance(artifacts, list):
155
+ for art in artifacts:
156
+ if isinstance(art, dict):
157
+ url = art.get("url") or art.get("signed_url") or art.get("download_url")
158
+ if isinstance(url, str) and url:
159
+ urls.append(url)
160
+ # Fallback: flat ``url`` / ``output_url`` keys used by some endpoints.
161
+ for key in ("url", "output_url", "video_url", "image_url", "audio_url"):
162
+ val = body.get(key)
163
+ if isinstance(val, str) and val and val not in urls:
164
+ urls.append(val)
165
+ return urls
166
+
167
+
168
+ def unwrap_error_body(text: str) -> str:
169
+ """Extract the inner ``{"detail"|"message"|"error": "..."}`` from a JSON body."""
170
+ stripped = text.strip()
171
+ if not stripped:
172
+ return text
173
+ try:
174
+ body = json.loads(stripped)
175
+ except (ValueError, TypeError):
176
+ return text
177
+ if isinstance(body, dict):
178
+ detail = extract_error_detail(body)
179
+ if detail:
180
+ return detail
181
+ return text
182
+
183
+
184
+ def extract_error_detail(body: dict) -> str:
185
+ """Pull a human-readable error string out of a *parsed* NVIDIA error body.
186
+
187
+ Callers should use this instead of stringifying the dict and running
188
+ ``unwrap_error_body`` on the repr — stringifying a dict produces Python
189
+ repr (single quotes), which isn't valid JSON, so round-tripping through
190
+ ``unwrap_error_body`` returns the ugly repr unchanged.
191
+
192
+ Lookup order: ``_raw`` (non-JSON fallback) → ``detail`` → ``message`` →
193
+ ``error`` (both string and nested-``{"message": ...}`` forms). Falls back
194
+ to ``json.dumps(body)`` so at least the user sees valid JSON rather than
195
+ a Python repr when no known key matches.
196
+ """
197
+ if not body:
198
+ return ""
199
+ raw = body.get("_raw")
200
+ if isinstance(raw, str) and raw:
201
+ return unwrap_error_body(raw)
202
+ for key in ("detail", "message", "error"):
203
+ value = body.get(key)
204
+ if isinstance(value, str) and value:
205
+ return value
206
+ if isinstance(value, dict):
207
+ nested = value.get("message") or value.get("detail")
208
+ if isinstance(nested, str) and nested:
209
+ return nested
210
+ try:
211
+ return json.dumps(body, ensure_ascii=False)
212
+ except (TypeError, ValueError):
213
+ return str(body)
214
+
215
+
216
+ def save_bytes_to_output_dir(
217
+ payload: bytes,
218
+ output_dir: Path | str | None,
219
+ *,
220
+ extension: str,
221
+ prefix: str = "nvidia",
222
+ ) -> str:
223
+ """Write bytes to ``output_dir`` and return a ``file://`` URL.
224
+
225
+ Used when NIM returns base64 — we persist to disk (SyncProviders write
226
+ local files so chained downstream steps can read via ``file://``).
227
+ When ``output_dir`` is None, write to the current working directory.
228
+ """
229
+ base = Path(output_dir) if output_dir is not None else Path.cwd()
230
+ base.mkdir(parents=True, exist_ok=True)
231
+ filename = f"{prefix}-{uuid.uuid4().hex[:12]}.{extension.lstrip('.')}"
232
+ path = base / filename
233
+ path.write_bytes(payload)
234
+ return path.resolve().as_uri()
235
+
236
+
237
+ class NvidiaClient:
238
+ """HTTP client shared across NVIDIA provider classes.
239
+
240
+ Owns a single ``httpx.Client`` configured with the ``nvapi-`` Bearer header.
241
+ Providers construct one per instance (or share via injection for tests).
242
+
243
+ Args:
244
+ api_key: NVIDIA API key. Falls back to ``NVIDIA_API_KEY`` /
245
+ ``NVIDIA_NIM_API_KEY`` env vars. Ignored when ``http_client`` is
246
+ injected.
247
+ gen_base_url: Override the image/video/audio generation base URL.
248
+ Also falls back to ``NVIDIA_GEN_BASE_URL`` env var — useful for
249
+ self-hosted NIM deployments.
250
+ chat_base_url: Override the chat/embeddings base URL. Falls back to
251
+ ``NVIDIA_CHAT_BASE_URL`` env var.
252
+ nvcf_status_url: Override the NVCF async-status base URL. Falls back
253
+ to ``NVIDIA_NVCF_STATUS_URL`` env var.
254
+ http_timeout: Default HTTP request timeout in seconds.
255
+ http_client: Pre-built ``httpx.Client`` to inject. When supplied, the
256
+ base URL and auth header are the caller's responsibility and all
257
+ base-URL / API-key overrides on this class are ignored.
258
+ """
259
+
260
+ def __init__(
261
+ self,
262
+ api_key: str | None = None,
263
+ *,
264
+ gen_base_url: str | None = None,
265
+ chat_base_url: str | None = None,
266
+ nvcf_status_url: str | None = None,
267
+ http_timeout: float = 120.0,
268
+ http_client: httpx.Client | None = None,
269
+ ) -> None:
270
+ self._api_key = resolve_api_key(api_key)
271
+ self._gen_base_url = (
272
+ gen_base_url or os.environ.get("NVIDIA_GEN_BASE_URL") or DEFAULT_GEN_BASE_URL
273
+ ).rstrip("/")
274
+ self._chat_base_url = (
275
+ chat_base_url or os.environ.get("NVIDIA_CHAT_BASE_URL") or DEFAULT_CHAT_BASE_URL
276
+ ).rstrip("/")
277
+ self._nvcf_status_url = (
278
+ nvcf_status_url or os.environ.get("NVIDIA_NVCF_STATUS_URL") or DEFAULT_NVCF_STATUS_URL
279
+ ).rstrip("/")
280
+ self._http_timeout = http_timeout
281
+ self._http_client = http_client
282
+ self._owns_client = http_client is None
283
+
284
+ # --- lifecycle ---
285
+
286
+ def http(self) -> httpx.Client:
287
+ """Lazy-create (or return injected) httpx client for generation endpoints."""
288
+ if self._http_client is None:
289
+ if not self._api_key:
290
+ raise ProviderError(
291
+ "No NVIDIA API key found. Set NVIDIA_API_KEY env var or pass api_key=.",
292
+ error_code=ProviderErrorCode.AUTH_FAILURE,
293
+ )
294
+ self._http_client = httpx.Client(
295
+ base_url=self._gen_base_url,
296
+ headers={
297
+ "Authorization": f"Bearer {self._api_key}",
298
+ "Accept": "application/json",
299
+ },
300
+ timeout=self._http_timeout,
301
+ )
302
+ self._owns_client = True
303
+ return self._http_client
304
+
305
+ def close(self) -> None:
306
+ """Release connection-pool resources for internally-created clients."""
307
+ if self._http_client is not None and self._owns_client:
308
+ self._http_client.close()
309
+ self._http_client = None
310
+
311
+ # --- accessors (needed by subclasses that construct per-call URLs) ---
312
+
313
+ @property
314
+ def chat_base_url(self) -> str:
315
+ return self._chat_base_url
316
+
317
+ @property
318
+ def api_key(self) -> str | None:
319
+ return self._api_key
320
+
321
+ # --- generation POST ---
322
+
323
+ def post_generation(self, model: str, payload: dict) -> tuple[int, dict, dict]:
324
+ """POST a generation request and return ``(status_code, body, headers)``.
325
+
326
+ ``body`` is the parsed JSON (or an ``{"_raw": bytes}`` fallback if the
327
+ response wasn't JSON — uncommon but guarded against). ``headers`` is a
328
+ lowercase-keyed dict to make ``NVCF-REQID`` lookup case-insensitive.
329
+
330
+ Raises ``ProviderError`` on transport failures; returns raw responses
331
+ on HTTP errors so callers can inspect the body for retry classification.
332
+ """
333
+ client = self.http()
334
+ path = build_generation_path(model)
335
+ try:
336
+ resp = client.post(path, json=payload)
337
+ except httpx.HTTPError as exc:
338
+ raise ProviderError(
339
+ f"NVIDIA submit failed (transport): {exc}",
340
+ error_code=map_nvidia_error(exc),
341
+ ) from exc
342
+
343
+ headers = {k.lower(): v for k, v in resp.headers.items()}
344
+ body = self._parse_json_body(resp)
345
+ return resp.status_code, body, headers
346
+
347
+ def poll_nvcf(self, request_id: str) -> tuple[int, dict, dict]:
348
+ """Poll NVCF for an async job. Returns ``(status_code, body, headers)``.
349
+
350
+ A 200 means the job is complete; a 202 means still running. Any other
351
+ status is an error and surfaces via the returned body for the caller
352
+ to classify. Headers are lowercase-keyed so callers can read
353
+ ``retry-after`` case-insensitively.
354
+ """
355
+ if not request_id:
356
+ raise ProviderError(
357
+ "Empty NVCF request id — cannot poll",
358
+ error_code=ProviderErrorCode.INVALID_INPUT,
359
+ )
360
+ client = self.http()
361
+ # NVCF status URL is on a *different* host than the gen client's
362
+ # base_url — pass the absolute URL so httpx bypasses base_url joining.
363
+ url = f"{self._nvcf_status_url}/{request_id}"
364
+ try:
365
+ resp = client.get(url)
366
+ except httpx.HTTPError as exc:
367
+ raise ProviderError(
368
+ f"NVIDIA poll failed (transport): {exc}",
369
+ error_code=map_nvidia_error(exc),
370
+ ) from exc
371
+ headers = {k.lower(): v for k, v in resp.headers.items()}
372
+ return resp.status_code, self._parse_json_body(resp), headers
373
+
374
+ def _parse_json_body(self, resp: httpx.Response) -> dict:
375
+ """Parse JSON; fall back to a dict wrapping raw text for non-JSON bodies."""
376
+ content_type = resp.headers.get("Content-Type", "")
377
+ if "json" not in content_type.lower():
378
+ return {"_raw": resp.text}
379
+ try:
380
+ return resp.json()
381
+ except (ValueError, json.JSONDecodeError):
382
+ return {"_raw": resp.text}
383
+
384
+ def wait_for_nvcf(
385
+ self,
386
+ request_id: str,
387
+ *,
388
+ timeout: float = 600.0,
389
+ initial_interval: float = 5.0,
390
+ ) -> dict:
391
+ """Block until an NVCF job completes; return the final body.
392
+
393
+ Used by SyncProvider subclasses (image, audio) to hide async-ness
394
+ from callers who expect a single blocking call. The interval doubles
395
+ every 30 seconds of elapsed time (matching the base class's
396
+ ``_adaptive_poll_interval``) but here we're in a simple function so we
397
+ inline the same formula.
398
+ """
399
+ start = time.monotonic()
400
+ while True:
401
+ status, body, headers = self.poll_nvcf(request_id)
402
+ if status == 200:
403
+ return body
404
+ if status in _NVCF_PENDING_STATUSES:
405
+ elapsed = time.monotonic() - start
406
+ if elapsed >= timeout:
407
+ raise ProviderError(
408
+ f"NVCF poll timeout after {elapsed:.1f}s (limit: {timeout}s)",
409
+ error_code=ProviderErrorCode.TIMEOUT,
410
+ )
411
+ doublings = int(elapsed / 30)
412
+ sleep_for = min(initial_interval * (2**doublings), 30.0)
413
+ time.sleep(sleep_for)
414
+ continue
415
+ detail = extract_error_detail(body)
416
+ raise ProviderError(
417
+ f"NVIDIA NVCF status {status}: {detail}",
418
+ error_code=map_nvidia_error(Exception(detail), status),
419
+ retry_after=retry_after_from_response(headers),
420
+ )
@@ -0,0 +1,50 @@
1
+ """Shared NVIDIA NIM error mapping — used by all NVIDIA providers.
2
+
3
+ NIM returns safety refusals as HTTP 400 with a ``Nemoguard`` / ``safety`` /
4
+ ``content policy`` marker in the body. That must classify as CONTENT_POLICY
5
+ (non-retryable) rather than a generic INVALID_INPUT — otherwise the caller
6
+ will burn retries on a deterministic refusal.
7
+ """
8
+
9
+ from genblaze_core.models.enums import ProviderErrorCode
10
+ from genblaze_core.providers.base import classify_api_error
11
+
12
+
13
+ def map_nvidia_error(exc: Exception, status_code: int | None = None) -> ProviderErrorCode:
14
+ """Map an NVIDIA NIM API exception / HTTP response to a ProviderErrorCode.
15
+
16
+ Args:
17
+ exc: The exception that occurred (or ``Exception(body_text)`` when
18
+ surfaced from an httpx response).
19
+ status_code: HTTP status code when available — takes priority over
20
+ string matching for unambiguous signals (401/403/429/5xx).
21
+ """
22
+ msg = str(exc).lower()
23
+ # Content-policy / safety refusal wins over status-code triage. NIM marks
24
+ # these with "nemoguard", "guardrail", or the standard "content policy" /
25
+ # "safety filter" terms. Classifying as CONTENT_POLICY prevents pointless
26
+ # retries on deterministic refusals.
27
+ if (
28
+ "nemoguard" in msg
29
+ or "guardrail" in msg
30
+ or "content_policy" in msg
31
+ or "content policy" in msg
32
+ or "safety filter" in msg
33
+ or "safety_filter" in msg
34
+ or "policy violation" in msg
35
+ or "blocked by safety" in msg
36
+ ):
37
+ return ProviderErrorCode.CONTENT_POLICY
38
+ # HTTP status codes take priority over message string-matching.
39
+ if status_code == 429:
40
+ return ProviderErrorCode.RATE_LIMIT
41
+ if status_code in (401, 403):
42
+ return ProviderErrorCode.AUTH_FAILURE
43
+ if status_code == 404:
44
+ return ProviderErrorCode.MODEL_ERROR
45
+ if status_code == 400:
46
+ return ProviderErrorCode.INVALID_INPUT
47
+ if status_code and status_code >= 500:
48
+ return ProviderErrorCode.SERVER_ERROR
49
+ # String-based fallback for SDK exceptions / transport errors.
50
+ return classify_api_error(exc)
@@ -0,0 +1,183 @@
1
+ """NvidiaAudioProvider — audio generation via NVIDIA NIM (Fugatto, Riva TTS).
2
+
3
+ Most NVIDIA audio endpoints return inline base64 audio. This provider is
4
+ synchronous; if an endpoint returns 202 we short-poll NVCF inside
5
+ ``generate()`` so the caller still sees a single blocking call.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import mimetypes
11
+ from pathlib import Path
12
+ from urllib.parse import urlparse
13
+
14
+ import httpx
15
+ from genblaze_core.exceptions import ProviderError
16
+ from genblaze_core.models.asset import Asset, AudioMetadata
17
+ from genblaze_core.models.enums import Modality, ProviderErrorCode
18
+ from genblaze_core.models.step import Step
19
+ from genblaze_core.providers.base import (
20
+ ProviderCapabilities,
21
+ SyncProvider,
22
+ validate_asset_url,
23
+ )
24
+ from genblaze_core.providers.model_registry import ModelRegistry
25
+ from genblaze_core.providers.retry import retry_after_from_response
26
+ from genblaze_core.runnable.config import RunnableConfig
27
+
28
+ from ._base import (
29
+ NvidiaClient,
30
+ extract_asset_urls,
31
+ extract_base64_assets,
32
+ extract_error_detail,
33
+ save_bytes_to_output_dir,
34
+ )
35
+ from ._errors import map_nvidia_error
36
+ from .models.audio import build_audio_registry
37
+
38
+
39
+ class NvidiaAudioProvider(SyncProvider):
40
+ """Adapter for NVIDIA NIM audio generation.
41
+
42
+ Args:
43
+ api_key: NVIDIA API key. Falls back to NVIDIA_API_KEY env var.
44
+ http_timeout: HTTP request timeout in seconds.
45
+ gen_base_url: Override the generation base URL (self-hosted NIM).
46
+ nvcf_status_url: Override the NVCF async-status URL.
47
+ nvcf_timeout: Max seconds to wait for async (202) completions.
48
+ output_dir: Where to save inline base64 payloads. Defaults to CWD.
49
+ http_client: Pre-built httpx.Client for tests / shared pools.
50
+ models: Optional custom ModelRegistry.
51
+ """
52
+
53
+ name = "nvidia-audio"
54
+
55
+ @classmethod
56
+ def create_registry(cls) -> ModelRegistry:
57
+ return build_audio_registry()
58
+
59
+ def __init__(
60
+ self,
61
+ api_key: str | None = None,
62
+ *,
63
+ http_timeout: float = 120.0,
64
+ gen_base_url: str | None = None,
65
+ nvcf_status_url: str | None = None,
66
+ nvcf_timeout: float = 120.0,
67
+ output_dir: Path | str | None = None,
68
+ http_client: httpx.Client | None = None,
69
+ models: ModelRegistry | None = None,
70
+ ) -> None:
71
+ super().__init__(models=models)
72
+ self._output_dir: Path | None = Path(output_dir) if output_dir is not None else None
73
+ self._nvcf_timeout = nvcf_timeout
74
+ self._client = NvidiaClient(
75
+ api_key=api_key,
76
+ gen_base_url=gen_base_url,
77
+ nvcf_status_url=nvcf_status_url,
78
+ http_timeout=http_timeout,
79
+ http_client=http_client,
80
+ )
81
+
82
+ def get_capabilities(self) -> ProviderCapabilities:
83
+ return ProviderCapabilities(
84
+ supported_modalities=[Modality.AUDIO],
85
+ supported_inputs=["text", "audio"],
86
+ accepts_chain_input=True,
87
+ models=self._models.known(),
88
+ output_formats=["audio/mpeg", "audio/wav", "audio/ogg"],
89
+ )
90
+
91
+ def close(self) -> None:
92
+ """Release httpx resources for internally-created clients."""
93
+ self._client.close()
94
+
95
+ def generate(self, step: Step, config: RunnableConfig | None = None) -> Step:
96
+ try:
97
+ payload = self.prepare_payload(step)
98
+ status, body, headers = self._client.post_generation(step.model, payload)
99
+ except ProviderError:
100
+ raise
101
+ except Exception as exc:
102
+ raise ProviderError(
103
+ f"NVIDIA audio generate failed: {exc}",
104
+ error_code=map_nvidia_error(exc),
105
+ ) from exc
106
+
107
+ if status == 202:
108
+ req_id = headers.get("nvcf-reqid")
109
+ if not req_id:
110
+ raise ProviderError(
111
+ "NVIDIA returned 202 without an NVCF-REQID header",
112
+ error_code=ProviderErrorCode.SERVER_ERROR,
113
+ )
114
+ body = self._client.wait_for_nvcf(str(req_id), timeout=self._nvcf_timeout)
115
+ elif status != 200:
116
+ detail = extract_error_detail(body)
117
+ raise ProviderError(
118
+ f"NVIDIA audio generate failed ({status}): {detail}",
119
+ error_code=map_nvidia_error(Exception(detail), status),
120
+ retry_after=retry_after_from_response(headers),
121
+ )
122
+
123
+ step.provider_payload = {"nvidia": {"status": "succeeded"}}
124
+
125
+ # Music models produce stereo; TTS mono. Spec.extras flags which.
126
+ spec = self._models.get(step.model)
127
+ is_music = bool(spec.extras.get("is_music"))
128
+
129
+ urls = extract_asset_urls(body)
130
+ if urls:
131
+ self._attach_url_assets(step, urls, is_music=is_music)
132
+ return step
133
+
134
+ payloads = extract_base64_assets(body)
135
+ if payloads:
136
+ for raw, mime in payloads:
137
+ media_type = mime or "audio/mpeg"
138
+ ext = mimetypes.guess_extension(media_type) or ".mp3"
139
+ url = save_bytes_to_output_dir(
140
+ raw, self._output_dir, extension=ext, prefix="nvidia-audio"
141
+ )
142
+ asset = Asset(url=url, media_type=media_type)
143
+ asset.audio = AudioMetadata(
144
+ channels=2 if is_music else 1,
145
+ codec=_codec_from_mime(media_type),
146
+ )
147
+ step.assets.append(asset)
148
+ return step
149
+
150
+ raise ProviderError(
151
+ "NVIDIA audio response contained no asset URL or base64 payload",
152
+ error_code=ProviderErrorCode.SERVER_ERROR,
153
+ )
154
+
155
+ def _attach_url_assets(self, step: Step, urls: list[str], *, is_music: bool) -> None:
156
+ """Attach hosted URLs as Assets atomically."""
157
+ new_assets: list[Asset] = []
158
+ for url in urls:
159
+ validate_asset_url(url)
160
+ path = urlparse(url).path
161
+ mime, _ = mimetypes.guess_type(path)
162
+ if mime is None or not mime.startswith("audio/"):
163
+ mime = "audio/mpeg"
164
+ asset = Asset(url=url, media_type=mime)
165
+ asset.audio = AudioMetadata(
166
+ channels=2 if is_music else 1,
167
+ codec=_codec_from_mime(mime),
168
+ )
169
+ new_assets.append(asset)
170
+ step.assets.extend(new_assets)
171
+
172
+
173
+ def _codec_from_mime(media_type: str) -> str:
174
+ """Map a MIME type to a stored ``AudioMetadata.codec`` short name."""
175
+ if "mpeg" in media_type or "mp3" in media_type:
176
+ return "mp3"
177
+ if "wav" in media_type or "wave" in media_type:
178
+ return "pcm"
179
+ if "ogg" in media_type:
180
+ return "vorbis"
181
+ if "flac" in media_type:
182
+ return "flac"
183
+ return "mp3"