Add a realtime Flux Klein example over Trickle

[zargarzadehm]

What did you build?

One sentence. What is the output?

Added flux-klein to livepeer/app-examples — a new example implementing realtime FLUX.2 [klein] image-to-image over the Trickle protocol on the Live Runner, closing issue #1.

Why does it matter?

One to two sentences. What problem does it solve, and for whom on the network?

Issue asked for a Trickle-protocol example on the new Live Runner so builders could see, end to end, how to run a realtime video-to-video model on Livepeer as a drop-in replacement for their existing cloud infra. flux-klein fills that gap: it receives a live video stream, transforms every frame against a text prompt with FLUX.2-klein-4B, and streams the result back, with prompt/seed/blend all adjustable mid-stream over /update.

Link to the work

Direct link to the merged PR, deployed tool, published docs, or equivalent. No link = no review.

• PR: https://github.com/livepeer/app-examples/pull/32
• Issue: https://github.com/livepeer/app-examples/issues/1

Evidence of impact

How is this being used? Who benefits? Quantify where possible (e.g. number of users, PRs merged, integrations adopted).

• Discussed the example and its approach directly with Rick (rickstaa) in the community — the original author of issue #1 requesting this Trickle/Live Runner example.
• Discord thread covering the build.

Community proof points

Link to the Discord thread or other signal. Reminder: you should also get 2-3 Orchestrators commenting their support for this work.

• Discord thread
• Discussed directly with Rick (rickstaa) in the community.

Amount requested

USD-equivalent (max $5,000). Include a brief breakdown if the amount is above $2,000.

$500 USD in LPT

[Mehrdad]

AI Pre-Screen — Retro Grant Review

Application: Add a realtime Flux Klein example over Trickle · Applicant: Moein (zargarzadehm) · Ask: $500 in LPT · Category: Retro Grants — Network Engineering SPE

• Scope — [Developers] The 5-Minute API. PR #32 adds flux-klein — realtime FLUX.2 [klein] img2img over trickle on the new live runner, with mid-stream prompt/seed/blend updates. Extends a maintainer-requested example; squarely in scope.

• Shipped — Reviewable, not yet merged. PR #32 open; Rick to review — “I need to fix the subgraph first but can review the pr this afternoon.” Merge is the only open gate.

• Proof point — Strong. Issue authored by Technical Director Rick (rickstaa), who worked with the applicant throughout (provided a GPU, guidance) and pre-blessed payout in the thread: “This looks very good … we can pay out … for the work.” Also “Great work @zargarzadehmoein!”

• Impact — Recognised, evidenced need with confirmed adoption. Extends the live-runner examples track Rick is driving. Named orchestrator pon | pon-node.eth stood it up on his own hardware — "ok we are up and running — Rick sent jobs against it (“I was abl to send jobs”*), and Sean independently tested it: “Runner works! … got it working.” Adoption is real and named, not projected.

• Quality — Working, measurably optimised: end-to-end throughput tuned from ~11.65 → ~24 fps (torch.compile max-autotune, compiled VAE, batching), with smoke-test.py, TESTING.md, and env-tuning notes in the README. Independently run by two third parties. Rick: “O wow this actually quite good.” Formal PR review pending.

• Proportionality — $500 for a complete, optimised example is well under the $5k ceiling — arguably under-priced given the perf work.

• Red flags — None material. Only open item: PR #32 not yet merged, but review is pre-arranged and payout pre-signalled by the Technical Director.

Verdict: READY FOR REVIEW — approve at $500. In scope, impact evidenced by named orchestrator adoption and Technical Director sign-off, quality clear. Recommend releasing on merge of PR #32.

[Mehrdad]

@zargarzadehm Please share your wallet address

[zargarzadehm]

@Mehrdad 0xD04561051640558177a6d61695159a7d6664819F

[jjassonn69]

Decision: Approved

The Review Team approves the requested $500 in full, subject to PR #35 completing the normal merge process with the original contributor’s attribution preserved.

The contribution addresses an established network engineering need by providing a self-contained FLUX.2-klein-4B realtime image-to-image example over Trickle and the Live Runner. It demonstrates persistent session handling, live prompt and parameter updates, frame-skipping for low-latency operation, health-gated model startup, and both offchain and paid onchain execution.

The original work from PR #32 was preserved and carried forward by the repository maintainer in PR #35. The maintainer updated it to the current USD-per-hour pricing schema, corrected the signer’s maximum ticket face value, aligned the Compose files with current repository conventions, and independently tested a paid Arbitrum mainnet session. Independent review also confirmed two deployed Flux Klein runners and completed a paid inference session that returned valid transformed frames.

The requested amount is modest and proportionate to the scope, technical complexity, network relevance, and demonstrated maintainer adoption.

Before payment, PR #35 should be updated against the current main branch, its non-mergeable state resolved, and the normal review and merge process completed. The final history should continue to credit the applicant and preserve their original contribution.

The submitted FLUX_BATCH=2 implementation currently returns only one output for a two-frame input because latent IDs cached from a B=1 call are incorrectly reused for B=2. Review testing confirmed that including the batch dimension in the latent-ID cache key fixes the issue. This fix or an equivalent solution should be applied before merge and protected by an output-count regression test.

The example currently assumes a locally hosted, unauthenticated remote signer. Its --signer option accepts only a URL and does not expose the authentication headers or token refresh required by hosted signers such as PymtHouse. This limitation does not justify reducing the award because the documented local onchain configuration works and paid execution was independently verified.

Future Follow-Ups

• Pin the Diffusers revision, Livepeer gateway commit, model revision, base image digest, and Python dependencies for reproducible builds.
• Serialize inference, live parameter updates, model reset, and session teardown. Deterministic testing confirmed that /update currently mutates shared model state while process_batch() is running in a worker thread. Teardown also calls MODEL.reset() and returns before the underlying asyncio.to_thread() inference has stopped, because cancelling the awaiting asyncio task does not cancel the thread.
• Fix finite-file EOF handling before merge. The runner currently responds to input EOF by canceling the inference worker, which can discard the in-flight or final buffered frame and produce an empty output.

Ecosystem follow-up: Extend the Livepeer live-runner payment flow to propagate the selected runner’s application identifier through LivePaymentSession, /generate-live-payment, and downstream metering. Current payment requests identify only the generic live type, causing services such as PymtHouse to report modelId=unknown. This is an upstream SDK/payment-attribution limitation and is not specific to the Flux Klein example.