genblaze-nvidia 0.2.0__tar.gz

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,76 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+
7
+ # Distribution / packaging
8
+ dist/
9
+ build/
10
+ *.egg-info/
11
+ *.egg
12
+ wheels/
13
+ /MANIFEST
14
+
15
+ # Virtual environments
16
+ .venv/
17
+ venv/
18
+ env/
19
+ ENV/
20
+
21
+ # IDE / editors
22
+ .vscode/
23
+ .idea/
24
+ *.swp
25
+ *.swo
26
+ *~
27
+ .project
28
+ .settings/
29
+
30
+ # Testing / coverage
31
+ .pytest_cache/
32
+ .coverage
33
+ .coverage.*
34
+ htmlcov/
35
+ coverage.xml
36
+ *.cover
37
+
38
+ # Type checking
39
+ .mypy_cache/
40
+ .pytype/
41
+ .pyre/
42
+
43
+ # Linting
44
+ .ruff_cache/
45
+
46
+ # OS files
47
+ .DS_Store
48
+ Thumbs.db
49
+ ehthumbs.db
50
+
51
+ # Environment / secrets
52
+ .env
53
+ .env.*
54
+ !.env.example
55
+ *.pem
56
+ *.key
57
+ credentials.json
58
+
59
+ # Jupyter
60
+ .ipynb_checkpoints/
61
+
62
+ # MkDocs build output
63
+ site/
64
+
65
+ # Claude Code — local/ephemeral
66
+ .claude/settings.local.json
67
+ .claude/worktrees/
68
+ CLAUDE.local.md
69
+
70
+ # Hypothesis test cache
71
+ .hypothesis/
72
+
73
+ # Temp files
74
+ *.tmp
75
+ *.bak
76
+ *.log
@@ -0,0 +1,198 @@
1
+ Metadata-Version: 2.4
2
+ Name: genblaze-nvidia
3
+ Version: 0.2.0
4
+ Summary: NVIDIA NIM / build.nvidia.com media provider adapters for genblaze (video, image, audio, chat)
5
+ Project-URL: Homepage, https://github.com/backblaze-labs/genblaze
6
+ Project-URL: Documentation, https://github.com/backblaze-labs/genblaze
7
+ Project-URL: Repository, https://github.com/backblaze-labs/genblaze
8
+ Project-URL: Changelog, https://github.com/backblaze-labs/genblaze/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/backblaze-labs/genblaze/issues
10
+ Author-email: Jeronimo De Leon <jdeleon@backblaze.com>
11
+ License-Expression: MIT
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Typing :: Typed
15
+ Requires-Python: >=3.11
16
+ Requires-Dist: genblaze-core<0.3,>=0.2.0
17
+ Requires-Dist: httpx>=0.24
18
+ Provides-Extra: chat
19
+ Requires-Dist: openai>=1.0; extra == 'chat'
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=7.0; extra == 'dev'
22
+ Description-Content-Type: text/markdown
23
+
24
+ <!-- last_verified: 2026-04-24 -->
25
+ # genblaze-nvidia
26
+
27
+ NVIDIA NIM / [build.nvidia.com](https://build.nvidia.com/models) provider adapters for
28
+ [genblaze](https://github.com/backblaze-labs/genblaze). Covers four modalities on one
29
+ `nvapi-` key: **video** (Cosmos, Edify), **image** (SDXL, SD 3.5, FLUX), **audio**
30
+ (Fugatto, Riva TTS), and **chat** (Nemotron, Llama, Mistral, Qwen, …).
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ pip install genblaze-nvidia # video/image/audio providers
36
+ pip install "genblaze-nvidia[chat]" # + the OpenAI SDK for LLM calls
37
+ ```
38
+
39
+ ## Auth
40
+
41
+ Sign up at [build.nvidia.com](https://build.nvidia.com) and create an API key
42
+ (starts with `nvapi-`). Export it:
43
+
44
+ ```bash
45
+ export NVIDIA_API_KEY=nvapi-...
46
+ ```
47
+
48
+ The free tier is rate-limited (~40 requests/minute per model) with no per-token
49
+ billing. Some models (Cosmos video) are still enterprise-gated as of
50
+ 2026-04 and will return `AUTH_FAILURE` for free-tier keys until you have access.
51
+
52
+ ## Two base URLs
53
+
54
+ NVIDIA's API spans two public hosts on the same key:
55
+
56
+ | Surface | Base URL | Used by |
57
+ |---|---|---|
58
+ | OpenAI-compatible chat / embeddings | `https://integrate.api.nvidia.com/v1` | `chat`, `achat` |
59
+ | Model-specific generation | `https://ai.api.nvidia.com/v1/genai/{vendor}/{slug}` | `NvidiaVideoProvider`, `NvidiaImageProvider`, `NvidiaAudioProvider` |
60
+ | NVCF async status | `https://api.nvcf.nvidia.com/v2/nvcf/pexec/status` | Async video polling |
61
+
62
+ All three are overridable per-constructor for self-hosted NIM deployments:
63
+
64
+ ```python
65
+ NvidiaImageProvider(
66
+ api_key="...",
67
+ gen_base_url="https://self-hosted.internal/v1",
68
+ nvcf_status_url="https://self-hosted.internal/v2/nvcf/pexec/status",
69
+ )
70
+ ```
71
+
72
+ ## Video — `NvidiaVideoProvider`
73
+
74
+ Cosmos and Edify Video return async (`202 Accepted` + `NVCF-REQID` header) and
75
+ the provider polls NVCF for completion. Some fast models return inline
76
+ synchronous responses — both paths converge on the same lifecycle.
77
+
78
+ ```python
79
+ from genblaze_core.models.step import Step
80
+ from genblaze_nvidia import NvidiaVideoProvider
81
+
82
+ provider = NvidiaVideoProvider() # reads NVIDIA_API_KEY
83
+ step = Step(
84
+ provider="nvidia-video",
85
+ model="nvidia/cosmos-1.0-7b-diffusion-text2world",
86
+ prompt="a drone flight over a coastal cliff at sunset",
87
+ )
88
+ result = provider.invoke(step)
89
+ print(result.assets[0].url) # file:// or https:// depending on response shape
90
+ ```
91
+
92
+ ## Image — `NvidiaImageProvider`
93
+
94
+ Synchronous inline base64 response. If an endpoint occasionally returns 202,
95
+ the provider short-polls NVCF inside `generate()` so the caller still sees
96
+ one blocking call.
97
+
98
+ ```python
99
+ from genblaze_nvidia import NvidiaImageProvider
100
+
101
+ provider = NvidiaImageProvider()
102
+ step = Step(
103
+ provider="nvidia-image",
104
+ model="stabilityai/stable-diffusion-3-5-large",
105
+ prompt="a studio photo of a brass teapot",
106
+ params={"cfg_scale": 4.5, "aspect_ratio": "1:1"},
107
+ )
108
+ result = provider.invoke(step)
109
+ ```
110
+
111
+ SDXL's schema differs from SD 3.5 / FLUX — the registry handles that
112
+ transparently, rewriting `prompt` + `negative_prompt` into the
113
+ `text_prompts` array SDXL expects.
114
+
115
+ ## Audio — `NvidiaAudioProvider`
116
+
117
+ ```python
118
+ from genblaze_nvidia import NvidiaAudioProvider
119
+
120
+ provider = NvidiaAudioProvider()
121
+
122
+ # TTS (mono)
123
+ step = Step(provider="nvidia-audio", model="nvidia/riva-tts", prompt="Hello, world.")
124
+
125
+ # Music / SFX (stereo)
126
+ step = Step(provider="nvidia-audio", model="nvidia/fugatto", prompt="upbeat synthwave intro")
127
+
128
+ result = provider.invoke(step)
129
+ ```
130
+
131
+ ## Chat — `chat` / `achat`
132
+
133
+ OpenAI-wire-compatible. Any model NIM currently serves works as a plain string —
134
+ no enumeration.
135
+
136
+ ```python
137
+ from genblaze_nvidia import chat
138
+
139
+ resp = chat(
140
+ "nvidia/nemotron-4-340b-instruct",
141
+ prompt="Summarize the Cosmos world foundation model in one sentence.",
142
+ )
143
+ print(resp.text)
144
+ ```
145
+
146
+ ```python
147
+ import asyncio
148
+ from genblaze_nvidia import achat
149
+
150
+ async def main():
151
+ r = await achat("meta/llama-3.3-70b-instruct", prompt="hi")
152
+ print(r.text)
153
+
154
+ asyncio.run(main())
155
+ ```
156
+
157
+ ## Models
158
+
159
+ Curated entries encode per-model behavior (SDXL's `text_prompts` shape,
160
+ canonical→native param aliases). Any model NVIDIA ships that isn't listed
161
+ still works via the permissive fallback spec — no release needed.
162
+
163
+ | Modality | Curated defaults |
164
+ |---|---|
165
+ | Video | `nvidia/cosmos-1.0-7b-diffusion-text2world`, `.../video2world`, `nvidia/cosmos-2.0-diffusion-*` |
166
+ | Image | `stabilityai/stable-diffusion-xl`, `.../stable-diffusion-3-5-{large,large-turbo,medium}`, `black-forest-labs/flux.1-{schnell,dev}` |
167
+ | Audio | `nvidia/fugatto`, `nvidia/riva-tts`, `nvidia/maxine-voice-font` |
168
+ | Chat | None — pure pass-through. Use any NIM model id. |
169
+
170
+ Discover live models at runtime (if you want the fresh catalog) via the
171
+ OpenAI-compatible `/v1/models` endpoint:
172
+
173
+ ```python
174
+ import httpx, os
175
+ r = httpx.get(
176
+ "https://integrate.api.nvidia.com/v1/models",
177
+ headers={"Authorization": f"Bearer {os.environ['NVIDIA_API_KEY']}"},
178
+ )
179
+ for m in r.json()["data"]:
180
+ print(m["id"])
181
+ ```
182
+
183
+ ## Error handling
184
+
185
+ NIM returns safety refusals as HTTP 400 with `Nemoguard` / safety markers in
186
+ the body. `map_nvidia_error` classifies these as `CONTENT_POLICY`
187
+ (non-retryable) instead of `INVALID_INPUT` — pipelines don't burn retries on
188
+ a deterministic refusal.
189
+
190
+ | HTTP / message | `ProviderErrorCode` |
191
+ |---|---|
192
+ | 401, 403 | `AUTH_FAILURE` |
193
+ | 404 | `MODEL_ERROR` |
194
+ | 429 | `RATE_LIMIT` |
195
+ | 400 with safety marker | `CONTENT_POLICY` |
196
+ | 400 plain | `INVALID_INPUT` |
197
+ | 5xx | `SERVER_ERROR` |
198
+ | transport timeout | `TIMEOUT` |
@@ -0,0 +1,175 @@
1
+ <!-- last_verified: 2026-04-24 -->
2
+ # genblaze-nvidia
3
+
4
+ NVIDIA NIM / [build.nvidia.com](https://build.nvidia.com/models) provider adapters for
5
+ [genblaze](https://github.com/backblaze-labs/genblaze). Covers four modalities on one
6
+ `nvapi-` key: **video** (Cosmos, Edify), **image** (SDXL, SD 3.5, FLUX), **audio**
7
+ (Fugatto, Riva TTS), and **chat** (Nemotron, Llama, Mistral, Qwen, …).
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pip install genblaze-nvidia # video/image/audio providers
13
+ pip install "genblaze-nvidia[chat]" # + the OpenAI SDK for LLM calls
14
+ ```
15
+
16
+ ## Auth
17
+
18
+ Sign up at [build.nvidia.com](https://build.nvidia.com) and create an API key
19
+ (starts with `nvapi-`). Export it:
20
+
21
+ ```bash
22
+ export NVIDIA_API_KEY=nvapi-...
23
+ ```
24
+
25
+ The free tier is rate-limited (~40 requests/minute per model) with no per-token
26
+ billing. Some models (Cosmos video) are still enterprise-gated as of
27
+ 2026-04 and will return `AUTH_FAILURE` for free-tier keys until you have access.
28
+
29
+ ## Two base URLs
30
+
31
+ NVIDIA's API spans two public hosts on the same key:
32
+
33
+ | Surface | Base URL | Used by |
34
+ |---|---|---|
35
+ | OpenAI-compatible chat / embeddings | `https://integrate.api.nvidia.com/v1` | `chat`, `achat` |
36
+ | Model-specific generation | `https://ai.api.nvidia.com/v1/genai/{vendor}/{slug}` | `NvidiaVideoProvider`, `NvidiaImageProvider`, `NvidiaAudioProvider` |
37
+ | NVCF async status | `https://api.nvcf.nvidia.com/v2/nvcf/pexec/status` | Async video polling |
38
+
39
+ All three are overridable per-constructor for self-hosted NIM deployments:
40
+
41
+ ```python
42
+ NvidiaImageProvider(
43
+ api_key="...",
44
+ gen_base_url="https://self-hosted.internal/v1",
45
+ nvcf_status_url="https://self-hosted.internal/v2/nvcf/pexec/status",
46
+ )
47
+ ```
48
+
49
+ ## Video — `NvidiaVideoProvider`
50
+
51
+ Cosmos and Edify Video return async (`202 Accepted` + `NVCF-REQID` header) and
52
+ the provider polls NVCF for completion. Some fast models return inline
53
+ synchronous responses — both paths converge on the same lifecycle.
54
+
55
+ ```python
56
+ from genblaze_core.models.step import Step
57
+ from genblaze_nvidia import NvidiaVideoProvider
58
+
59
+ provider = NvidiaVideoProvider() # reads NVIDIA_API_KEY
60
+ step = Step(
61
+ provider="nvidia-video",
62
+ model="nvidia/cosmos-1.0-7b-diffusion-text2world",
63
+ prompt="a drone flight over a coastal cliff at sunset",
64
+ )
65
+ result = provider.invoke(step)
66
+ print(result.assets[0].url) # file:// or https:// depending on response shape
67
+ ```
68
+
69
+ ## Image — `NvidiaImageProvider`
70
+
71
+ Synchronous inline base64 response. If an endpoint occasionally returns 202,
72
+ the provider short-polls NVCF inside `generate()` so the caller still sees
73
+ one blocking call.
74
+
75
+ ```python
76
+ from genblaze_nvidia import NvidiaImageProvider
77
+
78
+ provider = NvidiaImageProvider()
79
+ step = Step(
80
+ provider="nvidia-image",
81
+ model="stabilityai/stable-diffusion-3-5-large",
82
+ prompt="a studio photo of a brass teapot",
83
+ params={"cfg_scale": 4.5, "aspect_ratio": "1:1"},
84
+ )
85
+ result = provider.invoke(step)
86
+ ```
87
+
88
+ SDXL's schema differs from SD 3.5 / FLUX — the registry handles that
89
+ transparently, rewriting `prompt` + `negative_prompt` into the
90
+ `text_prompts` array SDXL expects.
91
+
92
+ ## Audio — `NvidiaAudioProvider`
93
+
94
+ ```python
95
+ from genblaze_nvidia import NvidiaAudioProvider
96
+
97
+ provider = NvidiaAudioProvider()
98
+
99
+ # TTS (mono)
100
+ step = Step(provider="nvidia-audio", model="nvidia/riva-tts", prompt="Hello, world.")
101
+
102
+ # Music / SFX (stereo)
103
+ step = Step(provider="nvidia-audio", model="nvidia/fugatto", prompt="upbeat synthwave intro")
104
+
105
+ result = provider.invoke(step)
106
+ ```
107
+
108
+ ## Chat — `chat` / `achat`
109
+
110
+ OpenAI-wire-compatible. Any model NIM currently serves works as a plain string —
111
+ no enumeration.
112
+
113
+ ```python
114
+ from genblaze_nvidia import chat
115
+
116
+ resp = chat(
117
+ "nvidia/nemotron-4-340b-instruct",
118
+ prompt="Summarize the Cosmos world foundation model in one sentence.",
119
+ )
120
+ print(resp.text)
121
+ ```
122
+
123
+ ```python
124
+ import asyncio
125
+ from genblaze_nvidia import achat
126
+
127
+ async def main():
128
+ r = await achat("meta/llama-3.3-70b-instruct", prompt="hi")
129
+ print(r.text)
130
+
131
+ asyncio.run(main())
132
+ ```
133
+
134
+ ## Models
135
+
136
+ Curated entries encode per-model behavior (SDXL's `text_prompts` shape,
137
+ canonical→native param aliases). Any model NVIDIA ships that isn't listed
138
+ still works via the permissive fallback spec — no release needed.
139
+
140
+ | Modality | Curated defaults |
141
+ |---|---|
142
+ | Video | `nvidia/cosmos-1.0-7b-diffusion-text2world`, `.../video2world`, `nvidia/cosmos-2.0-diffusion-*` |
143
+ | Image | `stabilityai/stable-diffusion-xl`, `.../stable-diffusion-3-5-{large,large-turbo,medium}`, `black-forest-labs/flux.1-{schnell,dev}` |
144
+ | Audio | `nvidia/fugatto`, `nvidia/riva-tts`, `nvidia/maxine-voice-font` |
145
+ | Chat | None — pure pass-through. Use any NIM model id. |
146
+
147
+ Discover live models at runtime (if you want the fresh catalog) via the
148
+ OpenAI-compatible `/v1/models` endpoint:
149
+
150
+ ```python
151
+ import httpx, os
152
+ r = httpx.get(
153
+ "https://integrate.api.nvidia.com/v1/models",
154
+ headers={"Authorization": f"Bearer {os.environ['NVIDIA_API_KEY']}"},
155
+ )
156
+ for m in r.json()["data"]:
157
+ print(m["id"])
158
+ ```
159
+
160
+ ## Error handling
161
+
162
+ NIM returns safety refusals as HTTP 400 with `Nemoguard` / safety markers in
163
+ the body. `map_nvidia_error` classifies these as `CONTENT_POLICY`
164
+ (non-retryable) instead of `INVALID_INPUT` — pipelines don't burn retries on
165
+ a deterministic refusal.
166
+
167
+ | HTTP / message | `ProviderErrorCode` |
168
+ |---|---|
169
+ | 401, 403 | `AUTH_FAILURE` |
170
+ | 404 | `MODEL_ERROR` |
171
+ | 429 | `RATE_LIMIT` |
172
+ | 400 with safety marker | `CONTENT_POLICY` |
173
+ | 400 plain | `INVALID_INPUT` |
174
+ | 5xx | `SERVER_ERROR` |
175
+ | transport timeout | `TIMEOUT` |
@@ -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
+ ]