Spaces:
Running
Running
File size: 4,758 Bytes
80d8c84 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 | # Training Connection Guide
This note closes `TRN 11`: how notebook-based training code should connect to
the ReplicaLab environment, which URLs to use, which client transport to
prefer, which secrets matter, and what to check first when a connection fails.
## Preferred Connection Order
Use the environment in this order:
1. Local backend for smoke tests and fast debugging
2. Hosted Hugging Face Space for shared team validation
3. H100 notebook runtime for training compute
The notebook runtime and the environment server are separate concerns. The
notebook supplies compute; the environment server supplies `reset`, `step`,
`state`, and `replay`.
## Base URLs
### Local
- REST base URL: `http://localhost:7860`
- WebSocket URL: `ws://localhost:7860/ws`
### Hosted
- Space page: `https://huggingface.co/spaces/ayushozha/replicalab`
- REST base URL: `https://ayushozha-replicalab.hf.space`
- WebSocket URL: `wss://ayushozha-replicalab.hf.space/ws`
## Which Transport To Use
Prefer `transport="rest"` first in notebooks:
- easier to debug with plain responses
- simpler error handling
- easier to reproduce single-step failures
Use `transport="websocket"` when you specifically want:
- long-lived per-connection sessions
- parity with frontend interactive behavior
- lower-overhead repeated `step()` calls after reset
## Required Secrets
### For environment access
No secret is required to talk to the current deterministic environment when it
is publicly reachable.
### For model downloads in notebook training
- `HF_TOKEN`
- needed for gated model downloads and authenticated Hugging Face access
- `REPLICALAB_URL`
- optional convenience variable for the environment base URL
- defaults can still be hardcoded in a notebook cell
### Important security note
Do not commit notebook URLs, notebook passwords, or temporary runtime access
links to the repo. Keep notebook credentials out-of-band.
## Minimal Client Usage
### Direct environment client
```python
import os
from replicalab.agents import build_baseline_scientist_action
from replicalab.client import ReplicaLabClient
base_url = os.getenv("REPLICALAB_URL", "http://localhost:7860")
with ReplicaLabClient(base_url, transport="rest") as client:
observation = client.reset(seed=42, scenario="ml_benchmark", difficulty="easy")
result = client.step(build_baseline_scientist_action(observation.scientist))
print(result.reward, result.done, result.info.verdict)
```
### Rollout worker
```python
import os
from replicalab.agents import build_baseline_scientist_action
from replicalab.client import ReplicaLabClient
from replicalab.training import RolloutWorker
base_url = os.getenv("REPLICALAB_URL", "http://localhost:7860")
with ReplicaLabClient(base_url, transport="rest") as client:
worker = RolloutWorker(client)
episode = worker.rollout(
build_baseline_scientist_action,
seed=42,
scenario="ml_benchmark",
difficulty="easy",
)
print(episode.total_reward, episode.verdict, episode.rounds_used)
```
## Troubleshooting
### `GET /` returns 404 or a simple landing page
That is not the training interface. The environment lives behind:
- `/health`
- `/scenarios`
- `/reset`
- `/step`
- `/ws`
### `Call reset() before step()`
The client has no active session yet. Always call `reset()` first.
### `404` on `/step`
Usually means the `session_id` is stale or the server restarted. Call `reset()`
again and start a fresh episode.
### WebSocket disconnects or times out
Retry with REST first. If REST works and WebSocket does not, the problem is
usually transport-specific rather than environment-specific.
### Space is up but root path looks broken
Check `GET /health` and `GET /scenarios` directly. The Space can be healthy
even if the root route is only a small landing page.
### Hugging Face Space is slow on the first request
Cold starts are expected on the free tier. Retry after the Space has fully
started.
### Notebook can download models but cannot reach the env
Verify:
1. `REPLICALAB_URL` points to the correct server
2. local server is running on port `7860` or the HF Space is healthy
3. you are using the matching transport (`rest` vs `websocket`)
## Relationship To Other Docs
- Deployment and hosted verification: [deployment.md](C:\Users\ayush\Desktop\Hackathons\replicalab-ai\docs\max\deployment.md)
- Client implementation: [client.py](C:\Users\ayush\Desktop\Hackathons\replicalab-ai\replicalab\client.py)
- Rollout implementation: [rollout.py](C:\Users\ayush\Desktop\Hackathons\replicalab-ai\replicalab\training\rollout.py)
This file is the notebook-facing connection note. Deployment-specific secret
management and HF Space operations remain in `docs/max/deployment.md`.
|