Skip to content

Commit d4b4f35

Browse files
nmharmon8nmharmon8
committed
Sync from diffio-ui
1 parent 41fad08 commit d4b4f35

28 files changed

Lines changed: 3795 additions & 2 deletions

‎AGENTS.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Repository Guidelines
2+
3+
## Project Structure and Module Organization
4+
* Source code lives in `src/diffio`, with the public SDK surface in `src/diffio/__init__.py`.
5+
* Tests live in `tests`, with shared fixtures in `tests/fixtures` and `tests/conftest.py`.
6+
* Tutorials and sample flows live in `tutorials`, for example `tutorials/audio-restoration-cli/README.md`.
7+
8+
## Build, Test, and Development Commands
9+
* `pip install -e .` installs the SDK in editable mode for local development.
10+
* `python -m pip install -r requirements-dev.txt` installs dev dependencies, including pytest.
11+
* `python -m pytest` runs the full test suite under `tests`.
12+
13+
## Coding Style and Naming Conventions
14+
* Use 4 space indentation and follow standard Python style conventions.
15+
* Keep public API names in `camelCase` to match the service contract, for example `create_project` arguments like `fileName`.
16+
* Do not add Python typing, type hints, or `typing` imports in this SDK.
17+
* Avoid `from __future__ import annotations` in SDK files.
18+
19+
## Testing Guidelines
20+
* Tests are written with pytest and live under `tests`.
21+
* Name tests with the `test_*.py` pattern, for example `tests/test_client.py`.
22+
* Prefer adding or updating fixtures in `tests/fixtures` when new API flows need stable inputs.
23+
24+
## Commit and Pull Request Guidelines
25+
* There is no enforced commit message format, use short imperative summaries that describe the change.
26+
* Pull requests should include a concise summary, any relevant issue links, and the exact test command used.
27+
* Include before and after notes when API behavior changes, plus doc updates in `README.md` when needed.
28+
29+
## SDK Documentation Sync
30+
* Whenever you change the SDK, update the website API documentation in `app/components/docs/` to match the new behavior.
31+
* Before finishing any SDK update, use a sub agent to review and apply the documentation updates in `app/components/docs/`, and do not exit until that review is complete.
32+
* Before finishing any SDK update, use a sub agent to review `README.md`, apply any updates needed to match the code, and do not exit until that review is complete.
33+
34+
## Configuration and Environment
35+
* Set `DIFFIO_API_KEY` for authenticated requests.
36+
* Override `DIFFIO_API_BASE_URL` when pointing at the Functions emulator or a non default endpoint.
37+
* Keep emulator base URLs consistent with the examples in `README.md`.

‎LICENSE‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
MIT License
22

3-
Copyright (c) 2026 Diffio AI
3+
Copyright (c) 2026 Diffio
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal
77
in the Software without restriction, including without limitation the rights
8-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8+
to use, copy, modify, merge, publish, distribute, sublicense, and or sell
99
copies of the Software, and to permit persons to whom the Software is
1010
furnished to do so, subject to the following conditions:
1111

‎README.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Diffio Python SDK
2+
3+
The Diffio Python SDK helps you call the Diffio API from Python. This version covers project creation, upload, generation, progress checks, and download URLs.
4+
Requires Python 3.8 or later.
5+
6+
## Install
7+
8+
```bash
9+
pip install diffio
10+
```
11+
12+
For local development:
13+
14+
```bash
15+
cd diffio-python
16+
pip install -e .
17+
```
18+
19+
## Configuration
20+
21+
Set the API key with `DIFFIO_API_KEY`. You can also override the base URL with `DIFFIO_API_BASE_URL`.
22+
23+
```bash
24+
export DIFFIO_API_KEY="diffio_live_..."
25+
export DIFFIO_API_BASE_URL="https://us-central1-diffioai.cloudfunctions.net"
26+
```
27+
28+
For emulators, set the base URL to the Functions emulator host.
29+
30+
```bash
31+
export DIFFIO_API_BASE_URL="http://127.0.0.1:5001/diffioai/us-central1"
32+
```
33+
34+
## Request options
35+
36+
Use request options to override headers, timeouts, retries, or the API key per request.
37+
You can also pass `timeoutInSeconds` as an alias for `timeout`.
38+
39+
```py
40+
from diffio import DiffioClient, RequestOptions
41+
42+
client = DiffioClient(apiKey="diffio_live_...")
43+
projects = client.list_projects(
44+
requestOptions=RequestOptions(
45+
headers={"X-Debug": "1"},
46+
timeout=30.0,
47+
maxRetries=2,
48+
retryBackoff=0.5,
49+
)
50+
)
51+
```
52+
53+
## Create a project and generation
54+
55+
`create_project` uploads the file and returns the project metadata.
56+
57+
```py
58+
from diffio import DiffioClient
59+
60+
client = DiffioClient(apiKey="diffio_live_...")
61+
file_path = "sample.wav"
62+
project = client.create_project(
63+
filePath=file_path,
64+
)
65+
66+
generation = client.create_generation(
67+
apiProjectId=project.apiProjectId,
68+
model="diffio-2",
69+
sampling={"steps": 12, "guidance": 1.5},
70+
)
71+
72+
print(generation.generationId)
73+
```
74+
75+
## Audio isolation helper
76+
77+
```py
78+
from diffio import DiffioClient
79+
80+
client = DiffioClient(apiKey="diffio_live_...")
81+
result = client.audio_isolation.isolate(
82+
filePath="sample.wav",
83+
model="diffio-2",
84+
sampling={"steps": 12, "guidance": 1.5},
85+
)
86+
87+
print(result.generation.generationId)
88+
```
89+
90+
## Restore audio in one call
91+
92+
This helper runs the full flow and returns the downloaded bytes plus a metadata dict.
93+
94+
```py
95+
from diffio import DiffioClient
96+
97+
client = DiffioClient(apiKey="diffio_live_...")
98+
audio_bytes, info = client.restore_audio(
99+
filePath="sample.wav",
100+
model="diffio-2",
101+
sampling={"steps": 12, "guidance": 1.5},
102+
onProgress=lambda progress: print(progress.status),
103+
)
104+
105+
if info["error"]:
106+
print(info["error"])
107+
else:
108+
with open("restored.mp3", "wb") as handle:
109+
handle.write(audio_bytes)
110+
111+
print(info["apiProjectId"], info["generationId"])
112+
```
113+
114+
## Generation progress
115+
116+
```py
117+
from diffio import DiffioClient
118+
119+
client = DiffioClient(apiKey="diffio_live_...")
120+
progress = client.generations.get_progress(
121+
generationId="gen_123",
122+
apiProjectId="proj_123",
123+
)
124+
125+
print(progress.status)
126+
```
127+
128+
## Generation download
129+
130+
```py
131+
from diffio import DiffioClient
132+
133+
client = DiffioClient(apiKey="diffio_live_...")
134+
download = client.generations.download(
135+
generationId="gen_123",
136+
apiProjectId="proj_123",
137+
downloadType="mp3",
138+
downloadFilePath="restored.mp3",
139+
)
140+
141+
print(download.downloadUrl)
142+
```
143+
144+
If you only need the URL, use `client.generations.get_download`.
145+
146+
## List projects
147+
148+
```py
149+
from diffio import DiffioClient
150+
151+
client = DiffioClient(apiKey="diffio_live_...")
152+
projects = client.projects.list()
153+
154+
for project in projects.projects:
155+
print(project.apiProjectId, project.status)
156+
```
157+
158+
## List project generations
159+
160+
```py
161+
from diffio import DiffioClient
162+
163+
client = DiffioClient(apiKey="diffio_live_...")
164+
generations = client.projects.list_generations(apiProjectId="proj_123")
165+
166+
for generation in generations.generations:
167+
print(generation.generationId, generation.status)
168+
```
169+
170+
## Webhooks portal access
171+
172+
```py
173+
from diffio import DiffioClient
174+
175+
client = DiffioClient(apiKey="diffio_live_...")
176+
portal = client.webhooks.get_portal_access(mode="test")
177+
print(portal.portalUrl)
178+
```
179+
180+
## Send a test webhook event
181+
182+
```py
183+
from diffio import DiffioClient
184+
185+
client = DiffioClient(apiKey="diffio_live_...")
186+
event = client.webhooks.send_test_event(
187+
eventType="generation.completed",
188+
mode="test",
189+
samplePayload={"apiProjectId": "proj_123"},
190+
)
191+
192+
print(event.svixMessageId)
193+
```
194+
195+
## Tutorials
196+
197+
* Audio restoration CLI tutorial: `tutorials/audio-restoration-cli/README.md`
198+
199+
## Runtime compatibility
200+
201+
Use Python 3.8 or later.
202+
203+
## Tests
204+
205+
```bash
206+
cd diffio-python
207+
python -m pip install -r requirements-dev.txt
208+
python -m pytest
209+
```

‎pyproject.toml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
[build-system]
2+
requires = ["setuptools>=68", "wheel"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "diffio"
7+
version = "0.1.0"
8+
description = "Python SDK for the Diffio API."
9+
readme = "README.md"
10+
requires-python = ">=3.8"
11+
license = { text = "MIT" }
12+
authors = [
13+
{ name = "Diffio" }
14+
]
15+
dependencies = [
16+
"httpx>=0.24.0"
17+
]
18+
classifiers = [
19+
"License :: OSI Approved :: MIT License",
20+
"Operating System :: OS Independent",
21+
"Programming Language :: Python :: 3",
22+
"Programming Language :: Python :: 3 :: Only",
23+
"Programming Language :: Python :: 3.8",
24+
"Programming Language :: Python :: 3.9",
25+
"Programming Language :: Python :: 3.10",
26+
"Programming Language :: Python :: 3.11",
27+
"Programming Language :: Python :: 3.12",
28+
]
29+
30+
[project.optional-dependencies]
31+
dev = [
32+
"build>=1.0",
33+
"pytest>=7.4",
34+
"twine>=5.0",
35+
]
36+
37+
[tool.setuptools]
38+
package-dir = { "" = "src" }
39+
40+
[tool.setuptools.packages.find]
41+
where = ["src"]
42+
43+
[tool.pytest.ini_options]
44+
testpaths = ["tests"]

‎requirements-dev.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
-r requirements.txt
2+
build>=1.0
3+
pytest>=7.4
4+
twine>=5.0

‎requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
httpx>=0.24.0

‎src/diffio/__init__.py‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
from .client import (
2+
AudioIsolationClient,
3+
DiffioClient,
4+
GenerationsClient,
5+
ProjectsClient,
6+
RequestOptions,
7+
WebhooksClient,
8+
)
9+
from .errors import DiffioApiError
10+
from .types import (
11+
AudioIsolationResult,
12+
CreateGenerationResponse,
13+
CreateProjectResponse,
14+
DownloadType,
15+
GenerationDownloadResponse,
16+
GenerationProgressResponse,
17+
GenerationProgressStage,
18+
GenerationWebhookEvent,
19+
GenerationWebhookStatus,
20+
ListProjectGenerationsResponse,
21+
ListProjectsResponse,
22+
ModelKey,
23+
ProjectGenerationSummary,
24+
ProjectSummary,
25+
WebhookEventType,
26+
WebhookMode,
27+
WebhookPortalResponse,
28+
WebhookTestEventResponse,
29+
)
30+
31+
__all__ = [
32+
"AudioIsolationClient",
33+
"AudioIsolationResult",
34+
"CreateGenerationResponse",
35+
"CreateProjectResponse",
36+
"DownloadType",
37+
"DiffioApiError",
38+
"DiffioClient",
39+
"GenerationDownloadResponse",
40+
"GenerationProgressResponse",
41+
"GenerationProgressStage",
42+
"GenerationWebhookEvent",
43+
"GenerationWebhookStatus",
44+
"GenerationsClient",
45+
"ListProjectGenerationsResponse",
46+
"ListProjectsResponse",
47+
"ModelKey",
48+
"ProjectGenerationSummary",
49+
"ProjectSummary",
50+
"ProjectsClient",
51+
"RequestOptions",
52+
"WebhookEventType",
53+
"WebhookMode",
54+
"WebhookPortalResponse",
55+
"WebhookTestEventResponse",
56+
"WebhooksClient",
57+
]
58+
59+
__version__ = "0.1.0"

‎src/diffio/__pycache__/__init__.cpython-310.pyc‎

1.11 KB
Binary file not shown.

‎src/diffio/__pycache__/client.cpython-310.pyc‎

28.5 KB
Binary file not shown.

‎src/diffio/__pycache__/errors.cpython-310.pyc‎

899 Bytes
Binary file not shown.

0 commit comments

Comments
 (0)