fix(sdk): rename wave -> wave_sdk (stdlib shadow), fix quickstart routes, add fresh-install CI

.github/workflows/smoke-install.yml

@@ -0,0 +1,78 @@
+name: smoke install
+
+# Regression guard for the fresh-install class of bug: builds the wheel from
+# this checkout, installs it (no `-e`, no repo on sys.path) into a throwaway
+# venv, and proves the installed package imports and reaches the live WAVE
+# gateway with the README's own quickstart. Running `pytest` from the repo
+# checkout does NOT catch this class of bug (the checkout dir is first on
+# sys.path and hides an import collision that only appears once the package
+# is actually installed and run from elsewhere) — this workflow is the one
+# gate that runs it the way a real `pip install wave-sdk` user does.
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: smoke-install-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build --wheel
+
+      - name: Create fresh venv (no repo on sys.path)
+        run: python -m venv "$RUNNER_TEMP/smoke"
+
+      - name: Install the built wheel
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          "$RUNNER_TEMP/smoke/bin/pip" install --upgrade pip
+          "$RUNNER_TEMP/smoke/bin/pip" install "$WHEEL"
+
+      - name: Import check (installed wheel, run away from the repo)
+        working-directory: ${{ runner.temp }}/smoke
+        run: |
+          bin/python -c "
+          import wave_sdk
+          print('wave_sdk', wave_sdk.__version__, 'imported from', wave_sdk.__file__)
+          from wave_sdk import Wave
+          print('Wave facade OK,', len([n for n in dir(wave_sdk) if n.endswith('API')]), 'API classes')
+          "
+
+      - name: Copy quickstart into the smoke venv's working directory
+        run: cp scripts/smoke_quickstart.py "$RUNNER_TEMP/smoke/smoke_quickstart.py"
+
+      - name: README quickstart (live gateway, real credentials)
+        working-directory: ${{ runner.temp }}/smoke
+        env:
+          WAVE_GATEWAY_API_KEY: ${{ secrets.WAVE_GATEWAY_API_KEY }}
+        run: |
+          if [ -z "$WAVE_GATEWAY_API_KEY" ]; then
+            echo "skipped: WAVE_GATEWAY_API_KEY absent (fork or unset)"
+            exit 0
+          fi
+          bin/python smoke_quickstart.py

CHANGELOG.md

@@ -6,7 +6,26 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-## [2.1.0] - 2026-09-01
+## [2.1.0] - 2026-09-01 (not yet published to PyPI)
+
+### Fixed
+
+- **Critical**: the top-level installable package was named `wave`, which
+  collides with the Python standard library's own `wave` module (WAV audio
+  I/O, `Lib/wave.py`, present in every CPython install). Because the stdlib
+  is earlier on `sys.path` than `site-packages`, a fresh `pip install
+  wave-sdk` followed by the README's own `from wave import Wave` resolved
+  to the STDLIB module and raised `ImportError: cannot import name 'Wave'
+  from 'wave'` — on every supported Python version, in every environment
+  except the SDK's own repo checkout (where the checkout directory being
+  first on `sys.path` masked the collision during development and in the
+  test suite). Verified live against the published 2.0.0 wheel from PyPI in
+  two isolated interpreters (3.14, 3.12); see the accompanying PR's LIVE
+  RECEIPTS. The installable package is renamed `wave_sdk` (`pip install
+  wave-sdk` still works; `from wave_sdk import Wave` now actually resolves
+  to the SDK). This does not change the 2.0.0 contract on PyPI — 2.0.0 was
+  never fixable in place and 2.1.0 has not shipped yet, so this lands before
+  the collision reaches a published release.
 
 ### Added
 
@@ -41,7 +60,7 @@ to 42, matching the TS facade 1:1.
   2026-09-01) has a corresponding Python method, or is in a justified
   allowlist (new backend surfaces neither SDK wraps yet, or pre-existing
   studio-ai drift that predates this release).
-- `tests/test_readme_quickstart.py` - asserts every `wave.<namespace>.<method>`
+- `tests/test_readme_quickstart.py` - asserts every `client.<namespace>.<method>`
   call in the README's quickstart resolves to a real SDK method.
 - Updated `tests/test_sdk_exports.py` for the new API count (42 + client)
   and version (2.1.0).
@@ -50,3 +69,13 @@ to 42, matching the TS facade 1:1.
 
 - Bumped to 2.1.0 (additive, semver-minor): no existing method signature
   changed.
+
+## [2.0.0] - 2026-04-03
+
+Initial public release of the WAVE Python SDK on PyPI as `wave-sdk`: 35 `*API`
+classes covering streaming, production, analytics, and content workflows
+(verified against the published wheel's `wave/__init__.py`; the PyPI package
+`Summary` metadata for this release says "33 API modules", which undercounts
+by 2 — a pre-existing metadata typo baked into the immutable 2.0.0 upload,
+noted here rather than fixed retroactively since PyPI release metadata for a
+published version cannot be edited).

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 WAVE, Inc.
+   Copyright 2026 WAVE Online, LLC
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

NOTICE

@@ -1,11 +1,11 @@
 WAVE
-Copyright 2026 WAVE, Inc.
+Copyright 2026 WAVE Online, LLC
 
-This product includes software developed at WAVE, Inc.
+This product includes software developed at WAVE Online, LLC
 (https://wave.online).
 
 The names "WAVE" and "WAVE Surfer", the WAVE wordmark, and the WAVE logo
-are trademarks of WAVE, Inc. and are NOT licensed under the Apache License,
+are trademarks of WAVE Online, LLC and are NOT licensed under the Apache License,
 Version 2.0. The Apache License grants rights to the software in this
 repository only; it does not grant permission to use the WAVE marks except
 as required for reasonable and customary use in describing the origin of the

README.md

@@ -1,6 +1,7 @@
 # WAVE SDK for Python
 
-Official Python SDK for the WAVE API by WAVE Inc.
+Media infrastructure for the agentic internet. Official Python SDK for WAVE, by
+WAVE Online, LLC.
 
 ## Installation
 
@@ -11,32 +12,19 @@ pip install wave-sdk
 ## Quick start
 
 ```python
-from wave import Wave
-
-wave = Wave(api_key="your-api-key", organization_id="org_123")
-
-# Create and start a live stream
-stream = wave.pipeline.create(title="My Stream", protocol="webrtc")
-wave.pipeline.start(stream.id)
-health = wave.pipeline.get_health(stream.id)
-print(f"Viewers: {health['viewer_count']}")
-
-# Create a virtual camera from NDI
-device = wave.prism.create_device(
-    name="PTZ Camera 1",
-    type="camera",
-    source_protocol="ndi",
-    source_endpoint="NDI-CAM-1",
-    node_id="node_abc",
-    ptz_enabled=True,
-)
-
-# Get analytics
-viewers = wave.pulse.get_viewer_analytics(time_range="24h")
-
-# Send a transcript email (mail:write) and read the usage ledger (meter:read)
-wave.mail.transcript_email(to="alice@example.com", transcript="...")
-ledger = wave.meter.ledger(channel="mail")
+from wave_sdk import Wave
+
+client = Wave(api_key="your-api-key", organization_id="org_123")
+
+# Search your organization's indexed media
+results = client.search.search(query="product launch")
+
+# List your org's published pricing tiers (requires the pricing:read scope)
+manifests = client.pricing.list_manifests()
+
+# Transcribe a recording and auto-generate captions for it
+transcription = client.transcribe.create(source_url="https://example.com/clip.mp4")
+captions = client.captions.generate(media_id=transcription.id, media_type="video")
 ```
 
 ## All 42 APIs
@@ -116,10 +104,10 @@ ledger = wave.meter.ledger(channel="mail")
 ## Error handling
 
 ```python
-from wave import WaveError, RateLimitError
+from wave_sdk import WaveError, RateLimitError
 
 try:
-    wave.pipeline.get("invalid-id")
+    client.clips.get("invalid-id")
 except RateLimitError as e:
     print(f"Rate limited. Retry after {e.retry_after}s")
 except WaveError as e:
@@ -134,4 +122,4 @@ except WaveError as e:
 
 ## License
 
-MIT - WAVE Inc.
+MIT - WAVE Online, LLC

pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.9"
 authors = [
-    {name = "WAVE Inc.", email = "sdk@wave.online"}
+    {name = "WAVE Online, LLC", email = "sdk@wave.online"}
 ]
 keywords = [
     "wave",
@@ -44,6 +44,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Video",
     "Topic :: Multimedia :: Sound/Audio",
     "Topic :: Software Development :: Libraries :: Python Modules",
@@ -52,6 +53,11 @@ classifiers = [
 dependencies = [
     "httpx>=0.25.0",
     "pydantic>=2.0.0",
+    # pydantic 2.x needs this to resolve `str | None`-style PEP 604 unions on
+    # Python 3.9, where `str | None` cannot be `eval()`'d natively (the SDK's
+    # models use `from __future__ import annotations` + the new union syntax
+    # for readability; requires-python allows 3.9, so this isn't optional).
+    "eval-type-backport>=0.2.0; python_version < '3.10'",
 ]
 
 [project.optional-dependencies]
@@ -78,7 +84,7 @@ Issues = "https://github.com/wave-av/sdk-python/issues"
 
 [tool.setuptools.packages.find]
 where = ["."]
-include = ["wave*"]
+include = ["wave_sdk*"]
 
 [tool.mypy]
 python_version = "3.9"
@@ -99,7 +105,7 @@ ignore = ["E501", "E701", "E702"]
 
 [tool.ruff.lint.per-file-ignores]
 # Public re-exports: the package __init__ exists to re-export the API surface.
-"wave/__init__.py" = ["F401"]
+"wave_sdk/__init__.py" = ["F401"]
 # Export-verification test imports every public symbol to assert it exists
 # (checked via __all__ / hasattr), so the names are intentionally "unused".
 "tests/test_sdk_exports.py" = ["F401"]

scripts/smoke_quickstart.py

@@ -0,0 +1,74 @@
+"""CI fresh-install smoke: proves the INSTALLED WHEEL imports and reaches the
+live WAVE gateway (https://api.wave.online), using the first two calls from
+README.md's quickstart (search + pricing) — the ones that resolve to routes
+confirmed live in the public OpenAPI spec and that respond deterministically
+(200, or an auth/scope error) without depending on a real, fetchable media
+URL. Never mocked: this is a real HTTP round trip against production.
+
+Exit 0 when the SDK reaches the gateway, whether or not the call is fully
+authorized (a 402 Payment Required or a 403 SCOPE_INSUFFICIENT both prove the
+request landed on a real, authenticating route). Exit 1 on anything that
+indicates the *installed package itself* is broken (ImportError, or any
+response that is not a recognized "reached the gateway" shape).
+
+Invoked by .github/workflows/smoke-install.yml against a wheel built from
+this checkout, installed into a throwaway venv with no repo source on
+sys.path — the class of bug this guards against (the SDK's own top-level
+package shadowing Python's stdlib `wave` module) is invisible to `pytest`
+run from the repo checkout, because the checkout directory being first on
+sys.path masks the collision. Only an install-from-wheel-elsewhere run like
+this one, or a real end user's environment, sees it.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+
+def main() -> int:
+    api_key = os.environ.get("WAVE_GATEWAY_API_KEY")
+    if not api_key:
+        print("skipped: WAVE_GATEWAY_API_KEY absent (fork or unset)")
+        return 0
+
+    # Import happens after the env-var short-circuit so a fork PR (no secret)
+    # still exercises the import path, which is the cheapest and most common
+    # way this class of bug shows up.
+    from wave_sdk import Wave, WaveError
+
+    client = Wave(api_key=api_key, organization_id="org_123")
+
+    reached_gateway = False
+
+    try:
+        results = client.search.search(query="product launch")
+        print(f"OK: search.search() -> {len(results.get('results', []))} results")
+        reached_gateway = True
+    except WaveError as e:
+        if e.status_code in (402, 403):
+            print(f"OK (reached gateway, gated): search.search() -> {e.status_code} {e.code}")
+            reached_gateway = True
+        else:
+            print(f"FAIL: search.search() -> {e.status_code} {e.code}: {e.message}", file=sys.stderr)
+
+    try:
+        client.pricing.list_manifests()
+        print("OK: pricing.list_manifests() -> 200")
+        reached_gateway = True
+    except WaveError as e:
+        if e.status_code in (402, 403):
+            print(f"OK (reached gateway, gated): pricing.list_manifests() -> {e.status_code} {e.code}")
+            reached_gateway = True
+        else:
+            print(f"FAIL: pricing.list_manifests() -> {e.status_code} {e.code}: {e.message}", file=sys.stderr)
+
+    if not reached_gateway:
+        print("FAIL: neither quickstart call reached the gateway", file=sys.stderr)
+        return 1
+
+    print("QUICKSTART OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/conftest.py

@@ -9,5 +9,5 @@ def api_key():
 
 @pytest.fixture
 def wave_client():
-    from wave import Wave
+    from wave_sdk import Wave
     return Wave(api_key="test-api-key", organization_id="org_test")

tests/test_contract_coverage.py

@@ -145,7 +145,7 @@ def test_no_stale_mapping_or_allowlist_entries():
 
 
 def test_mapped_methods_exist_on_wave():
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     missing = []
     for op_id, (namespace, method) in MAPPING.items():