Launching Your First Run

This guide uses the RunRLClient to upload assets, launch a run, and monitor completion. It mirrors the flows exposed in the RunRL web UI but keeps everything scriptable.

Prerequisites

SDK installed and configured (see Installation & Setup).
Prompt dataset stored as JSONL lines.
Reward function defined in Python with a reward_fn(completion, **kwargs) signature.

1. Upload Artifacts

from runrl import RunRLClient

client = RunRLClient()

prompt = client.files.upload_path(
    "prompt_examples.jsonl",
    file_type="prompt",
    name="qa_prompts",
)

reward = client.files.create_from_content(
    name="keyword_reward",
    file_type="reward_function",
    content="""\
def reward_fn(completion, **kwargs):
    response = completion[0]["content"].lower()
    return 1.0 if "banana" in response else 0.0
""",
)

2. Launch the Run

client.runs.create returns a RunRLPollingFuture. The initial run payload is available immediately; call .result() to wait for terminal status.

future = client.runs.create(
    model="Qwen/Qwen2.5-3B-Instruct",
    prompt_file_id=prompt.id,
    reward_file_id=reward.id,
    type="reward_function",
    completion_length=256,
    epochs=1,
)

print("submitted run", future.initial.id, future.initial.status)
run = future.result()  # Blocks until COMPLETED / FAILED / CANCELLED
print("final status", run.status)

Async variant

import asyncio
from runrl import AsyncRunRLClient


async def main():
    async with AsyncRunRLClient() as client:
        future = await client.runs.create(
            model="Qwen/Qwen2.5-3B-Instruct",
            prompt_file_id="PROMPT_UUID",
            reward_file_id="REWARD_UUID",
            type="reward_function",
        )
        run = await future
        print(run.status)

asyncio.run(main())

3. Monitor Progress

history = client.runs.history(run.id)
logs = client.runs.logs(run.id)
metrics = client.runs.metrics(run.id)  # Weights & Biases snapshot

for entry in history:
    print(entry["status"], entry["timestamp"])

To stream logs incrementally:

for line in client.runs.stream_logs(run.id):
    print(line)

4. Cancel When Needed

client.runs.cancel(run.id)

This will also stop the future from polling—future.cancel() internally calls the same endpoint.

5. Clean Up

Files and runs are soft-deleted by default. Permanently removing a file requires force=True:

client.files.delete(prompt.id, force=True)
client.files.delete(reward.id, force=True)

Ready for more? Browse the API Reference or copy a complete example from the Examples gallery.

Launching Your First Run

On this page