Skip to content

docs: showcase advanced training parameters in README #1

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
AndresNinou wants to merge 1 commit into
base: main
Choose a base branch
from
+57 −0
Open

docs: showcase advanced training parameters in README #1

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
57 changes: 57 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,63 @@ sudo python quickstart.py --prompt "pick up the red cube"

---

## Advanced training

The quickstart submits a one-epoch LoRA fine-tune with sensible defaults.
For real production work, `client.training.lora_finetune(...)` accepts
eight extra optional kwargs that thread straight through to the
LeRobot training pipeline. Every value is bounds-checked server-side
before a GPU is provisioned, so a bad config fails fast and you don't
pay for it.

```python
from reflex import Reflex

client = Reflex()
job = client.training.lora_finetune(
hf_source_uri="hf://lerobot/aloha_sim_transfer_cube_human",
model_name="pi05-aloha-cube",
model_version="v1",
# Core knobs:
max_steps=2000,
batch_size=8,
learning_rate=1e-4,
lora_rank=16,
# Advanced — all optional, all bounds-checked server-side:
lora_alpha=32, # [1, 256]
lora_dropout=0.05, # [0.0, 0.5]
target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
warmup_steps=200, # [0, max_steps/2]
gradient_checkpointing=True, # save VRAM
freeze_vision_encoder=True, # standard for LoRA
dtype="bfloat16", # {"bfloat16", "float32"}
save_freq=500, # [50, max_steps]
)

print(job["training_job_id"])
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check for identifier naming patterns in the README

rg -n 'run_id|training_job_id' README.md

Repository: reflex-inc/quickstart

Length of output: 653

Fix inconsistent key name in code example.

Line 152 accesses job["training_job_id"], but the documentation consistently references run_id as the returned identifier (lines 26, 192, 196, 246, 249). Update the code example to use the correct key name for consistency.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 152, The README example uses job["training_job_id"] which
is inconsistent with the documented identifier name run_id; update the example
to access the returned identifier using job["run_id"] (or the equivalent run_id
key) so the snippet matches other references to run_id throughout the docs and
examples.

```
Comment on lines +128 to +153
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

🧩 Analysis chain

🌐 Web query:

What is the latest published version of reflex-sdk on PyPI?

💡 Result:

The latest published version of reflex-sdk on PyPI is v0.1.4.[1]

Citations:

🏁 Script executed:

# First, understand the repository structure
git ls-files | head -20

Repository: reflex-inc/quickstart

Length of output: 151

🏁 Script executed:

# Look for SDK-related files, particularly the Reflex class and training API
fd -t f "reflex" | grep -E "\.(py|toml|md)$" | head -20

Repository: reflex-inc/quickstart

Length of output: 47

🏁 Script executed:

# Check for setup.py or pyproject.toml to understand version info
fd -t f -E "__pycache__" "(setup|pyproject)" | head -10

Repository: reflex-inc/quickstart

Length of output: 80

🏁 Script executed:

# Search for lora_finetune method definition
rg "lora_finetune" -t py

Repository: reflex-inc/quickstart

Length of output: 127

🏁 Script executed:

# Look for the Reflex class definition
rg "class Reflex" -t py

Repository: reflex-inc/quickstart

Length of output: 47

🏁 Script executed:

cat -n pyproject.toml

Repository: reflex-inc/quickstart

Length of output: 2101

🏁 Script executed:

cat -n quickstart.py

Repository: reflex-inc/quickstart

Length of output: 25221

🏁 Script executed:

# Get the specific lines from README to compare
sed -n '128,153p' README.md | cat -n

Repository: reflex-inc/quickstart

Length of output: 1240

Update the README code example to match the actual SDK in quickstart.py.

The documented API in README.md (lines 128–153) does not match the working implementation in quickstart.py (lines 154–159). The README shows parameters like model_version, max_steps, batch_size, lora_rank, lora_alpha, lora_dropout, target_modules, warmup_steps, gradient_checkpointing, freeze_vision_encoder, dtype, and save_freq, plus a different import and instantiation pattern (from reflex import Reflex / Reflex()), but the actual code uses only hf_source_uri, model_name, base_model, and epochs with reflex.Client(api_key=...). Developers following the README will encounter errors. Replace the README example with the actual working call pattern from quickstart.py, or document which parameters are genuinely supported by reflex-sdk>=0.1.4.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 128 - 153, The README example uses a non-matching API
surface (Reflex()/lots of params) — update it to match quickstart.py by
replacing the import/instantiation and call to reflect the real SDK: use
reflex.Client(api_key=...) instead of Reflex(), and call training.lora_finetune
with the actual supported parameters (hf_source_uri, model_name, base_model,
epochs) or, if you want to keep the extended knobs, explicitly document that
only reflex-sdk>=0.1.4 supports them and list which parameters are accepted;
ensure the README's example and parameter names (training.lora_finetune,
hf_source_uri, model_name, base_model, epochs, reflex.Client) exactly match the
implementation in quickstart.py.


| Kwarg | Default if omitted | Bounds | What it does |
|---|---|---|---|
| `lora_alpha` | derived from `lora_rank` | [1, 256] | LoRA scaling factor |
| `lora_dropout` | `0.0` | [0.0, 0.5] | Dropout on LoRA layers |
| `target_modules` | full pi0.5 set | whitelist below | Modules to LoRA-adapt |
| `warmup_steps` | `100` | [0, `max_steps/2`] | LR warmup length |
| `gradient_checkpointing` | `False` | bool | Trade compute for VRAM |
| `freeze_vision_encoder` | `True` | bool | Freeze the vision tower |
| `dtype` | `"bfloat16"` | `{"bfloat16", "float32"}` | Compute dtype |
| `save_freq` | `500` | [50, `max_steps`] | Steps between checkpoints |
Comment on lines +155 to +164
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Consider clarifying the "derived from lora_rank" default.

The table states that lora_alpha defaults to a value "derived from lora_rank" when omitted. For users to understand the actual default behavior, consider documenting the derivation formula or providing an example (e.g., "typically 2 * lora_rank" or "defaults to lora_rank").

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 155 - 164, Clarify the README's `lora_alpha` default
by replacing "derived from `lora_rank`" with the explicit derivation formula or
an example; update the table row for `lora_alpha` to state the exact rule (e.g.,
"defaults to 2 * lora_rank" or "defaults to lora_rank — typically 2 *
lora_rank") and, if applicable, add a short parenthetical example to show
numeric behavior when `lora_rank` is X; edit the README entry for `lora_alpha`
(and nearby `lora_rank` docs if present) so users see the concrete default
computation and an example.


`target_modules` whitelist for pi0.5: `q_proj`, `k_proj`, `v_proj`,
`o_proj`, `gate_proj`, `up_proj`, `down_proj`, `action_in_proj`,
`action_out_proj`. Pass any subset.

The same kwargs work on `client.training.full_finetune(...)` except
for the LoRA-specific ones (`lora_alpha`, `lora_dropout`,
`target_modules`) — those are rejected on full fine-tunes.

---

## Expected output

```
Expand Down
Loading