chore: make src the server package root (#117)

* Restructure server packages under src

* Add training e2e checks

Author: ShubyM

.dockerignore

@@ -0,0 +1,6 @@
+.git
+**/.venv
+**/__pycache__
+**/*.pyc
+.ruff_cache
+.pytest_cache

.github/workflows/build-and-push.yml

@@ -13,13 +13,13 @@ jobs:
       matrix:
         include:
           - image_name: gateway
-            context: src/server
+            context: .
             dockerfile: src/server/Dockerfile.gateway
           - image_name: server
-            context: src/server
+            context: .
             dockerfile: src/server/Dockerfile
           - image_name: client
-            context: examples
+            context: .
             dockerfile: examples/autoresearch/Dockerfile
     permissions:
       contents: read

.github/workflows/build-pr.yml

@@ -10,13 +10,13 @@ jobs:
       matrix:
         include:
           - image_name: gateway
-            context: src/server
+            context: .
             dockerfile: src/server/Dockerfile.gateway
           - image_name: server
-            context: src/server
+            context: .
             dockerfile: src/server/Dockerfile
           - image_name: client
-            context: examples
+            context: .
             dockerfile: examples/autoresearch/Dockerfile
     permissions:
       contents: read

Makefile

@@ -13,26 +13,45 @@ HOST           ?= 127.0.0.1
 PORT           ?= 9003
 # The fully qualified base URL used by local CLI tools and clients
 BASE_URL       ?= http://$(HOST):$(PORT)
-TEST_PYTHONPATH ?= examples/sft/pig-latin
+UNIT_TESTS ?= tests.test_gateway_paths tests.test_snapshot_agent tests.test_trainer_optimizer_correctness tests.test_worker_launch_processor
+# Only forward BASE_URL to e2e when the user supplied it. The Makefile default
+# is for local CLI usage; e2e should start its own backend by default.
+TRAINING_TEST_BASE_URL ?= $(if $(filter environment command line,$(origin BASE_URL)),$(BASE_URL),)
+TRAINING_TEST_EXTRA ?= gpu
+TRAINING_TEST_ARGS ?=
+PIGLATIN_TEST_PYTHONPATH ?= examples/sft/pig-latin
+
+# CUDA_VISIBLE_DEVICES can be provided either as an environment variable or as a
+# Make variable, and is inherited by the backend/eval subprocesses.
+ifneq ($(origin CUDA_VISIBLE_DEVICES),undefined)
+  export CUDA_VISIBLE_DEVICES
+endif
 
 help:
 	@echo "make server                              # $(BASE_MODEL), SAMPLING_BACKEND=$(SAMPLING_BACKEND), port $(PORT)"
 	@echo "make server BASE_MODEL=google/gemma-4-e2b SAMPLING_BACKEND=vllm"
 	@echo "VLLM_ARCHITECTURE_OVERRIDE=Gemma4ForCausalLM make vllm BASE_MODEL=google/gemma-4-e2b"
-	@echo "make test | lint | fmt"
+	@echo "make test                               # fast unit tests"
+	@echo "make test e2e tiny-lora|tiny-fft|tiny-rl|lora-textsql|fft-gsm8k|fft-gsm8k-x2  # tiny-* = fast overfit smoke tests"
+	@echo "make test e2e tiny-lora BASE_URL=http://host:9003"
+	@echo "CUDA_VISIBLE_DEVICES=0 make test e2e tiny-fft"
+	@echo "make test e2e tiny-fft TRAINING_TEST_ARGS='steps=20'"
+	@echo "make test e2e fft-gsm8k TRAINING_TEST_ARGS='steps=10 eval_examples=8 extra=\"batch=2\"'"
+	@echo "make test piglatin                      # pig-latin example end-to-end tests"
+	@echo "make lint | fmt"
 
 # ---------------------------------------------------------------------------
 # Server
 # ---------------------------------------------------------------------------
 server:
 	@-kill -9 $$(lsof -ti:$(PORT)) 2>/dev/null || true
-	cd src/server && BASE_MODEL="$(BASE_MODEL)" SAMPLING_BACKEND="$(SAMPLING_BACKEND)" \
+	BASE_MODEL="$(BASE_MODEL)" SAMPLING_BACKEND="$(SAMPLING_BACKEND)" \
 	  uv run --extra $(if $(filter vllm,$(SAMPLING_BACKEND)),gpu,cpu) \
-	  python -m uvicorn gateway:app --host $(HOST) --port $(PORT)
+	  python -m uvicorn server.gateway:app --host $(HOST) --port $(PORT)
 
 vllm:
-	cd src/server && BASE_MODEL="$(BASE_MODEL)" \
-	  uv run --extra vllm python -m vllm_sampler
+	BASE_MODEL="$(BASE_MODEL)" \
+	  uv run --extra vllm python -m server.vllm_sampler
 
 # ---------------------------------------------------------------------------
 # CLI
@@ -42,14 +61,40 @@ ifeq (cli,$(firstword $(MAKECMDGOALS)))
   $(eval $(CLI_ARGS):;@:)
 endif
 
+ifeq (test,$(firstword $(MAKECMDGOALS)))
+  TEST_MODE := $(word 2,$(MAKECMDGOALS))
+  TEST_SCENARIO := $(word 3,$(MAKECMDGOALS))
+  TEST_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
+  ifneq ($(TEST_ARGS),)
+    $(eval $(TEST_ARGS):;@:)
+  endif
+endif
+
 cli:
 	@cd dev/tools && BASE_URL="$(BASE_URL)" uv run python cli.py $(CLI_ARGS)
 
 # ---------------------------------------------------------------------------
 # Dev
 # ---------------------------------------------------------------------------
 test:
-	PYTHONPATH="$(TEST_PYTHONPATH)" uv --project examples run python -m unittest discover -s tests
+	@mode="$(TEST_MODE)"; \
+	scenario="$(TEST_SCENARIO)"; \
+	if [ -z "$$mode" ] || [ "$$mode" = "unit" ]; then \
+	  uv run --frozen --exact --extra cpu python -m unittest $(UNIT_TESTS); \
+	elif [ "$$mode" = "e2e" ]; then \
+	  if [ -z "$$scenario" ]; then \
+	    echo "Missing e2e scenario. Expected tiny-lora, tiny-fft, tiny-rl, lora-textsql, fft-gsm8k, or fft-gsm8k-x2."; \
+	    exit 2; \
+	  fi; \
+	  set -- "scenario=$$scenario" "uv_extra=$(TRAINING_TEST_EXTRA)"; \
+	  if [ -n "$(TRAINING_TEST_BASE_URL)" ]; then set -- "$$@" "base_url=$(TRAINING_TEST_BASE_URL)"; fi; \
+	  uv run --extra "$(TRAINING_TEST_EXTRA)" python scripts/run_training_e2e.py "$$@" $(TRAINING_TEST_ARGS); \
+	elif [ "$$mode" = "piglatin" ]; then \
+	  PYTHONPATH="$(PIGLATIN_TEST_PYTHONPATH)" uv --project examples run python -m unittest discover -s tests; \
+	else \
+	  echo "Unknown test mode '$$mode'. Expected unit, e2e, or piglatin."; \
+	  exit 2; \
+	fi
 
 lint:
 	uvx ruff check .
@@ -66,8 +111,8 @@ GCP_PROJECT ?= cdrollouts-sunilarora
 IMAGE_TAG   ?= latest
 
 build-images:
-	cd src/server && DOCKER_BUILDKIT=1 docker build -t gcr.io/$(GCP_PROJECT)/open-rl-server:$(IMAGE_TAG) -f Dockerfile .
-	cd src/server && DOCKER_BUILDKIT=1 docker build -t gcr.io/$(GCP_PROJECT)/open-rl-gateway:$(IMAGE_TAG) -f Dockerfile.gateway .
+	DOCKER_BUILDKIT=1 docker build -t gcr.io/$(GCP_PROJECT)/open-rl-server:$(IMAGE_TAG) -f src/server/Dockerfile .
+	DOCKER_BUILDKIT=1 docker build -t gcr.io/$(GCP_PROJECT)/open-rl-gateway:$(IMAGE_TAG) -f src/server/Dockerfile.gateway .
 
 push-images:
 	docker push gcr.io/$(GCP_PROJECT)/open-rl-server:$(IMAGE_TAG)
@@ -106,4 +151,3 @@ push-vm:
 # Pull changes from the remote VM back to the local workspace
 pull-vm:
 	rsync -avz --exclude '.git' --exclude '.venv' --exclude '__pycache__' --exclude '*.pyc' --exclude '.DS_Store' $(REMOTE_HOST):~/open-rl/ ./
-

dev/tools/cli.py

@@ -44,7 +44,7 @@ def list_adapters(args):
       # Format timestamp if possible
       try:
         # If it's a float timestamp
-        if isinstance(created_at, (int, float)):
+        if isinstance(created_at, int | float):
           dt = datetime.fromtimestamp(created_at)
           created_at = dt.strftime("%Y-%m-%d %H:%M:%S")
         # If it's an ISO string (from metadata.json)

docs/blog/assets/local-to-cloud.svg

@@ -16,7 +16,7 @@ Start the server:
 
 ```bash
 BASE_MODEL="google/gemma-3-1b-pt" \
-  uv run uvicorn src.gateway:app --host 0.0.0.0 --port 9003
+  uv run uvicorn server.gateway:app --host 0.0.0.0 --port 9003
 ```
 
 Then write your training loop with the Tinker SDK — 4 API primitives are all you need:

docs/blog/from-mac-to-gke.md

@@ -15,10 +15,9 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 Start the API server and trainer with the default torch sampling backend:
 
 ```bash
-cd src/server
 BASE_MODEL=google/gemma-4-e2b \
 SAMPLING_BACKEND=torch \
-uv run --extra cpu python -m uvicorn gateway:app --host 127.0.0.1 --port 9003
+uv run --extra cpu python -m uvicorn server.gateway:app --host 127.0.0.1 --port 9003
 ```
 
 Because `REDIS_URL` is unset, this starts the API server and trainer loop in one
@@ -28,20 +27,18 @@ For a separate vLLM sampler, use two terminals:
 
 ```bash
 # Terminal 1: vLLM sampler
-cd src/server
 BASE_MODEL=google/gemma-4-e2b \
 VLLM_ARCHITECTURE_OVERRIDE=Gemma4ForCausalLM \
 CUDA_VISIBLE_DEVICES=0 \
-uv run --extra vllm python -m vllm_sampler
+uv run --extra vllm python -m server.vllm_sampler
 ```
 
 ```bash
 # Terminal 2: API server and trainer
-cd src/server
 BASE_MODEL=google/gemma-4-e2b \
 SAMPLING_BACKEND=vllm \
 CUDA_VISIBLE_DEVICES=1 \
-uv run --extra gpu python -m uvicorn gateway:app --host 127.0.0.1 --port 9003
+uv run --extra gpu python -m uvicorn server.gateway:app --host 127.0.0.1 --port 9003
 ```
 
 The equivalent Makefile shortcuts are:
@@ -95,18 +92,18 @@ Kubernetes deployment manifests set these variables in pod specs. The important
 REDIS_URL=redis://redis-service:6379 \
 VLLM_URL=http://vllm-service:8001 \
 BASE_MODEL=google/gemma-4-e2b \
-uv run uvicorn src.gateway:app --host 0.0.0.0 --port 8000
+uv run uvicorn server.gateway:app --host 0.0.0.0 --port 8000
 ```
 
 ```bash
 # Trainer worker pod
 REDIS_URL=redis://redis-service:6379 \
 BASE_MODEL=google/gemma-4-e2b \
-uv run python -m src.clock_cycle
+uv run python -m server.training_requests_processor
 ```
 
 ```bash
 # vLLM worker pod
 BASE_MODEL=google/gemma-4-e2b \
-uv run uvicorn src.vllm_sampler:app --host 0.0.0.0 --port 8001
+uv run uvicorn server.vllm_sampler:app --host 0.0.0.0 --port 8001
 ```

docs/configuration.md

@@ -67,8 +67,7 @@ All commands below assume you are in the **repository root** directory.
 Patch vLLM `0.20.0` for Gemma 4 LoRA support.
 
 ```bash
-(cd src/server && \
- uv run --extra vllm python scripts/patch_vllm_lora_dedup.py)
+uv run --extra vllm python src/server/scripts/patch_vllm_lora_dedup.py
 ```
 
 ### 2. Start the vLLM Sampler

docs/setup/local-setup.md

@@ -21,8 +21,8 @@ RUN npm install -g @google/gemini-cli
 
 WORKDIR /app
 
-COPY pyproject.toml uv.lock README.md ./
-COPY autoresearch ./autoresearch
+COPY examples/pyproject.toml examples/uv.lock examples/README.md ./
+COPY examples/autoresearch ./autoresearch
 
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --frozen