Epic: Client SDK with BYOC release (livepeer-client)

[rickstaa]

Outcome

Ship the v1 livepeer-client SDK so callers can request any Livepeer capability — not just live video-to-video — using one of three idiomatic verbs (run / stream / live) without having to understand orchestrators, discovery, trickle, or local payment signing.

The same call a developer runs in the Developer Dashboard playground is the call that ships into their app.

Spec

Design lives in livepeer-specs / client-sdk.md. Update the spec rather than this issue body when the design moves.

Key shape (see spec for full details):

• Gateway(token=…, signer_url=…, …) — config carrier, reused across N calls
• gw.run(capability, *, input=, model=) → plain return value (Replicate / fal idiom)
• gw.stream(capability, …) → StreamResponse yielding StreamEvent (OpenAI / Anthropic idiom)
• gw.live(capability, …) → LiveSession with publish / subscribe / control / events (LiveKit idiom)
• Async variants (run_async, stream_async) first-class
• Three-distribution packaging: livepeer-client, livepeer-runner, livepeer-trickle under livepeer.* PEP 420 namespace

Blockers

The v1 release is gated on the following PRs landing:

• livepeer/go-livepeer#3869 — Adds remote signing for BYOC to go-livepeer
• livepeer/go-livepeer#3914 — Adds stream-based payment tracking, needed for the remote signer above
• livepeer/livepeer-python-gateway#6 — Adds BYOC support to the SDK (foundation for Gateway / run / stream / live)

Work checklist (post-blocker)

Public API

• Gateway config carrier with token / signer / discovery / orch precedence rules
• gw.live(capability, ...) → LiveSession (delegates to existing start_lv2v for live-video-to-video)
• gw.run(...) skeleton (raises NotImplementedError until BYOC HTTP routing on orch)
• gw.stream(...) skeleton (raises NotImplementedError until BYOC SSE routing on orch)
• StreamEvent / StreamResponse / AsyncStreamResponse types
• run_async / stream_async variants
• Wire gw.run to BYOC HTTP route once upstream lands
• Wire gw.stream to BYOC SSE route once upstream lands

Packaging (paired with #8 C12)

• Move repo to uv workspace — packages/livepeer-client, packages/livepeer-runner, packages/livepeer-trickle
• PEP 420 namespace: no __init__.py at src/livepeer/; CI check to enforce
• livepeer-gateway deprecation shim re-exports public names with DeprecationWarning
• PyPI publish workflow per package

Docs / examples

• Migrate examples from start_lv2v(...) to Gateway(...).live(...)
• One worked example per verb (run, stream, live)
• README quickstart matching Replicate / fal / OpenAI style

Open questions

See the Open questions before implementation section in the spec — primarily around BYOC HTTP / SSE routing path on the orchestrator and publish / subscribe lazy vs. eager creation.

Out of scope for v1

Item	Why deferred
Gateway.submit(...) handle pattern (.wait / .cancel / .id)	Needs orch-side reattach + cancel semantics designed first
Non-video live capabilities (raw trickle fallback)	No non-video live capability exists upstream yet
Sync wrapper for live()	Live jobs are inherently async; a sync wrapper would mask that

Related

• Spec: client-sdk.md
• Companion epic: #8 (Pipeline SDK — deploy-side)
• Initial implementation: #6

Status

Blocked on the three upstream PRs listed above. Design locked.