Rank prompt lock ​

A Rank session always evaluates clips under the same prompt mode. The first upload to a fresh session captures that mode and locks the session to it:

  • A non-empty prompt locks the session to that exact string (trimmed, case-sensitive).
  • An omitted, empty, or whitespace-only prompt locks the session to no prompt (rankPrompt: null).

Every subsequent upload must either omit prompt (the locked value is reused) or pass the exact same string. Passing a different prompt — or a non-empty prompt against a no-prompt lock — fails with RANK_PROMPT_MISMATCH.

States ​

A Rank session is in one of three states.

Empty. No videos uploaded yet, no prompt locked. The session was just created or just reset. The next upload sets the lock — either to a prompt string or to no prompt.

Locked. At least one video is uploaded and the session is committed to a prompt mode. Reads (get_or_create, get_ranked) report rankPromptLocked: true plus rankPrompt (a string, or null for no-prompt mode). Uploads only accept matching or omitted prompts.

Reset. Calling worldjen.rank.reset() (or worldjen rank reset from the CLI) clears all videos, releases the lock, and returns the session to Empty. The session id is preserved so existing references stay valid.

Transitions ​

From Empty, an upload with prompt="X" moves to Locked(X). An upload with prompt=None, omitted prompt, or prompt="" moves to Locked(null) — the session is locked to no prompt.

From Locked(X) where X is a non-empty string, an upload with prompt="X" or omitted prompt stays in Locked(X) and appends the video. An upload with prompt="Y" where Y != X, or an empty/missing prompt when the lock expects a string, is rejected as a prompt mismatch.

From Locked(null), an upload with omitted or empty prompt stays in Locked(null). An upload with any non-empty prompt is rejected as a prompt mismatch.

From Locked(X) or Empty, reset returns to Empty and clears the prompt.

Patterns ​

Sweep one prompt across many variants. Lock the session on the first upload, then keep uploading without prompt:

python
import worldjen

worldjen.rank.upload("variant_a.mp4", prompt="a cat sitting on a windowsill")
for path in ("variant_b.mp4", "variant_c.mp4", "variant_d.mp4"):
    worldjen.rank.upload(path)              # uses the locked prompt

Rank without a prompt. Lock the session to no-prompt mode on the first upload, then omit prompt on the rest:

python
import worldjen

worldjen.rank.upload("variant_a.mp4")       # locks to no prompt
worldjen.rank.upload("variant_b.mp4")       # must also omit prompt

Switch to a new prompt. Reset first; the next upload starts a fresh lock.

python
worldjen.rank.reset()
worldjen.rank.upload("variant_a.mp4", prompt="a dog running through grass")

Recover from a mismatch. Catch RankPromptMismatchError and decide: either reset and start a new ranking, or drop the override and re-upload with the locked prompt.

python
try:
    worldjen.rank.upload("variant.mp4", prompt="a dog")
except worldjen.RankPromptMismatchError as exc:
    print(exc.detail)
    worldjen.rank.reset()
    worldjen.rank.upload("variant.mp4", prompt="a dog")

From the CLI, the mismatch surfaces as exit code 2 with the server detail and the worldjen rank reset command to recover.