Skip to content

docs: add a capabilities column and say what is not covered #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rickstaa wants to merge 1 commit into
base: rs/ollama-multi-model
Choose a base branch
from
Open

docs: add a capabilities column and say what is not covered #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 23 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,21 @@ Need a schema that isn't here? [Open an issue](https://github.com/livepeer/runne

## Examples

| Example | Goal | Registration | Mode | Transport | Pricing |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------ | ----------- | ----------------- | ------- |
| [`hello-world`](./hello-world) | The simplest app: one request, one response | dynamic | single-shot | HTTP (JSON) | fixed |
| [`tiles`](./tiles) | Capacity fan-out — one call per tile | dynamic | single-shot | HTTP (base64 PNG) | fixed |
| [`api-proxy`](./api-proxy) | Pass calls through to a hosted API — the operator holds the key, callers pay per call | static | single-shot | HTTP (JPEG bytes) | fixed |
| [`echo`](./echo) | Realtime video, transformed and echoed back | dynamic | persistent | trickle | hour |
| [`vllm`](./vllm) | Drop-in OpenAI API; the client stays unmodified | static | single-shot | HTTP + SSE | hour |
| [`realtime-transcription`](./realtime-transcription) | Audio up, transcripts back, on one socket | dynamic | persistent | WebSocket | hour |
| [`ollama`](./ollama) | One container, several models, each its own priced app | dynamic | single-shot | HTTP + SSE | hour |
| Example | Goal | Registration | Mode | Transport | Pricing | Capabilities |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------ | ----------- | ----------------- | ------- | ------------ |
| [`hello-world`](./hello-world) | The simplest app: one request, one response | dynamic | single-shot | HTTP (JSON) | fixed | 1 |
| [`tiles`](./tiles) | Capacity fan-out — one call per tile | dynamic | single-shot | HTTP (base64 PNG) | fixed | 1 |
| [`api-proxy`](./api-proxy) | Pass calls through to a hosted API — the operator holds the key, callers pay per call | static | single-shot | HTTP (JPEG bytes) | fixed | 1 |
| [`echo`](./echo) | Realtime video, transformed and echoed back | dynamic | persistent | trickle | hour | 1 |
| [`vllm`](./vllm) | Drop-in OpenAI API; the client stays unmodified | static | single-shot | HTTP + SSE | hour | 1 |
| [`realtime-transcription`](./realtime-transcription) | Audio up, transcripts back, on one socket | dynamic | persistent | WebSocket | hour | 1 |
| [`ollama`](./ollama) | One container, several models, each its own priced app | dynamic | single-shot | HTTP + SSE | hour | N |

Start with `hello-world` (the smallest end-to-end path); the others each layer on one new idea. More will follow, including a full example that exercises every feature. Each is self-contained and runs **offchain** (free, no wallet); most also run **on-chain** (paid) — see each README.
Start with `hello-world` (the smallest end-to-end path); the others each layer on one new idea. Each is self-contained and runs **offchain** (free, no wallet); most also run **on-chain** (paid) — see each README.

This set stays **minimal and curated**: it covers each value of the axes above (registration, mode, transport, pricing), not one example per app. New examples land here only when they fill a gap in that table — apps built on the runner belong in their own repos, listed under [External examples](#external-examples).
**Capabilities** is how many apps one process registers. It is `1` everywhere except `ollama`, which registers one per model from a single container — several priced capabilities behind one deployment.

This set stays **minimal and curated**: it covers each value of the axes above (registration, mode, transport, pricing, capabilities), not one example per app. New examples land here only when they fill a gap in that table — apps built on the runner belong in their own repos, listed under [External examples](#external-examples).

## Registration

Expand Down Expand Up @@ -90,6 +92,16 @@ The client side depends on the runner's mode:

Each example's `client.py` shows its exact calls — grep `# Livepeer:` to find them.

## Not covered here

The runner does a few more things that no example demonstrates, listed so their absence reads as a choice rather than a limit:

- **Proxy mode.** Registering with `proxy: true` makes the orchestrator hand out an opaque per-session URL from a configurable template instead of the default `/apps/{runner}/session/{session}/app` path, and the template's placeholder may sit in the **host**. That gives each session its own origin, which matters for browser apps (cookies, CORS, service workers are per-origin) and for anything serving assets from absolute paths. There is no example because the app-side change is one boolean — everything interesting is orchestrator configuration.
- **`label` and `version`** on registration. Both are carried through to discovery and neither changes behaviour, so they are yours to use for operational bookkeeping.
- **Changing `status` while running.** A runner can heartbeat itself out of `ready` to stop receiving sessions, and back again. Useful when one process registers several apps that share hardware, but the SDK has no public setter for it yet.

Two known gaps in the runner itself are worth reading before you deploy: capacity is tracked per registration rather than per machine ([go-livepeer#4015](https://github.com/livepeer/go-livepeer/issues/4015)), and a persistent session whose client disappears is never released offchain ([go-livepeer#4016](https://github.com/livepeer/go-livepeer/issues/4016)).

## External examples

Apps that integrate the live runner and live in their own repos — production deployments and standalone examples alike. This table is links-only: the code, CI, and support stay with the author.
Expand Down
Loading