agents.md

The whole koyu entity model, for agents. Read this only when a task requires going beyond a template's recipe.

Entities

Episode    one robot trajectory: data.parquet + <camera>.mp4s + episode.json
           immutable after commit; carries provenance (source_run_id,
           source_checkpoint, policy_name) and optionally a reward verdict
Manifest   a named set of episodes = a dataset (type: teleop|eval|intervention|synthetic)
           success_rate rolls up from member episodes' rewards
Run        one experiment: files (checkpoints, metrics.jsonl, results.json)
           + linked manifests. Runs nest into a tree inside a project.
Project    a tree of runs + project files (README, code). Templates are
           public projects; clone lineage is a first-class field.

Experiments, not code: use git for code. A run stores what an experiment produced and what data it was produced from — that link is the provenance.

Reading (no auth for public entities)

GET  /api/projects/{id}                      -> metadata + files dict
POST /api/projects/{id}/files/download       -> presigned URLs   (same for runs)
GET  /api/projects/{id}/runs                 -> the run tree (flat, parent_id)
GET  /api/runs/{id}/manifests                -> linked datasets
GET  /api/manifests/{id}/episodes            -> episode index (paginated, limit<=100)
POST /api/manifests/{id}/episodes/batch-get  -> per-file presigned URLs (1h expiry)

Quirk: listing endpoints need ?scope=public when unauthenticated; by-id reads of public entities need nothing.

Prefer the CLI over raw REST for bulk data — it already handles pagination, URL expiry, concurrency, and resume:

koyu fetch <proj_|run_ id> <dir>     mirror files
koyu pull  <mf_ id> <dir>            materialize a dataset (dataloader-ready)

Writing (requires KOYU_TOKEN)

POST /api/projects                            create (name, is_public)
POST /api/projects/{id}/runs                  create run (name, parent_id?)
koyu push <run_|proj_ id> <paths…> --base .   two-step blake3-diffed upload
POST /api/runs/{id}/manifests                 link a dataset to a run
POST /api/episodes/upload → PUT files → /commit   then /api/manifests/{id}/episodes/add

Conventions when publishing results: checkpoints under checkpoints/ (best.pt, last.pt), training curves as metrics.jsonl (one JSON object per log step, any keys), eval summaries as results.json. Episode source_checkpoint is a path within a run's files — keep it true.

Auth model

Public reads: anonymous, always. Writes and private reads: bearer token (KOYU_TOKEN), minted at koyu.dev/settings/tokens. On rented hardware use a short-lived child token. If you need a token mid-task, stop and ask the user — never proceed without one being provided deliberately.