diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4cf0eaa --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# Working in this repo + +These are **teaching examples**. Each one exists to make a single mechanism legible, so +it is read at least as often as it is run — clarity beats cleverness, and the smallest +change that makes the point is the right one. + +Two files hold everything you need, and neither is loaded automatically, so read them +rather than inferring the conventions from the code: + +- [CONTRIBUTING.md](./CONTRIBUTING.md) — what belongs here and what doesn't, commit + format, the formatting hooks, and the rule that every example must run **offchain end + to end** before it ships. +- [README.md](./README.md) — what the examples are, and the axis table that decides + whether a new one belongs at all. Most proposed examples don't. + +This file deliberately holds no rules of its own. If something is worth knowing, it goes +in one of the two above, where human contributors see it too. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fded5dc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +See [AGENTS.md](./AGENTS.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7bdbe4a..382a65a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Thank you for considering contributing to the live runner example apps. These ar ## Scope: a minimal, curated set -This repo covers each value of the example axes (registration, mode, transport, pricing) once — it is not a collection of apps built on the runner. +This repo covers each value of the [axis table](./README.md#examples) once — it is not a collection of apps built on the runner. The table is the source of truth for what counts as a gap. - **In scope** — bug fixes, doc improvements, and new examples that fill a gap in the README's axis table. Open an issue first to agree on the gap. - **Out of scope** — new app examples that don't add axis coverage. Publish those in your own repo (name it `-livepeer-runner`, add the `livepeer-runner` GitHub topic, mention Livepeer in the description) and open a PR that adds one row to the README's [External examples](./README.md#external-examples) table. @@ -38,6 +38,11 @@ uvx pre-commit run --all-files Local hooks are optional — CI runs the same checks either way. +Two conventions the tooling can't enforce: + +- **Keep the `# Livepeer:` markers accurate.** They number the SDK calls in each `runner.py` / `client.py` in the order they happen, and the README sends readers to them as the way to see an example's whole Livepeer surface. A change that adds or removes a call should renumber them and update the file's docstring. +- **Never commit media or model weights.** Each example gitignores them (`*.wav`, `*.mp4`, model directories); sample clips are generated by the commands in its README. Check `git status` before `git add -A`. + ### Pull Requests - Keep PRs **small and focused** — one example or one concern per PR. diff --git a/README.md b/README.md index c80d06f..159705e 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ The client side depends on the runner's mode: - **Single-shot** — **discover → call**: find the app via `runner_selector`, then one `call_runner`. The orchestrator reserves a session for the call and releases it when the response returns; on the paid path `call_runner` answers the 402 payment challenge inline. (`hello-world`, `tiles`, `api-proxy`, `vllm`, `ollama`) - **Persistent** — **discover → reserve → call → release**: reserve a session (`reserve_session`), call it — `call_runner`, streamed frames, or a WebSocket, depending on transport — then release it (`stop_runner_session`), which settles payment on-chain. (`echo`, `realtime-transcription`) -Each example's `client.py` shows its exact calls — grep `# Livepeer:` to find them. +Each example's `client.py` shows its exact calls, numbered in the order they happen — grep `# Livepeer:` to find them. ## Not covered here