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.
- genblaze_nvidia/__init__.py +19 -0
- genblaze_nvidia/_base.py +420 -0
- genblaze_nvidia/_errors.py +50 -0
- genblaze_nvidia/audio.py +183 -0
- genblaze_nvidia/chat.py +213 -0
- genblaze_nvidia/image.py +157 -0
- genblaze_nvidia/models/__init__.py +15 -0
- genblaze_nvidia/models/audio.py +49 -0
- genblaze_nvidia/models/image.py +96 -0
- genblaze_nvidia/models/video.py +76 -0
- genblaze_nvidia/py.typed +0 -0
- genblaze_nvidia/video.py +237 -0
- genblaze_nvidia-0.2.0.dist-info/METADATA +198 -0
- genblaze_nvidia-0.2.0.dist-info/RECORD +16 -0
- genblaze_nvidia-0.2.0.dist-info/WHEEL +4 -0
- genblaze_nvidia-0.2.0.dist-info/entry_points.txt +4 -0
|
@@ -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
|
+
]
|
genblaze_nvidia/_base.py
ADDED
|
@@ -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)
|
genblaze_nvidia/audio.py
ADDED
|
@@ -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"
|