docs(architecture): document the wedge server architecture pattern - #109
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new architecture document describing Reflex’s “Wedge” composition pattern for the inference server, covering Safety (ActionGuard), Adaptive denoising, Deadline fallback, and Split (cloud/edge) concepts.
Changes:
- Introduces
docs/architecture_wedges.mdwith an end-to-end/actflow walkthrough and wedge-by-wedge explanations. - Adds a startup flag reference section, plus runtime API and observability/telemetry examples.
- Provides deployment “composition patterns” and further-reading links.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "mode": "clamp", | ||
| "max_consecutive_clamps": 10 | ||
| } |
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
Already addressed in commit 061f4c0. The safety.json schema now shows only the SafetyLimits fields (position_min, position_max, velocity_max, effort_max, workspace_min, workspace_max) without the ActionGuard-specific mode and max_consecutive_clamps settings.
| reflex serve ./my-export/ --cloud-fallback-url http://cloud-vla:8000 | ||
|
|
||
| # Cloud-first with edge fallback: | ||
| reflex serve ./my-export/ --cloud-fallback-url http://cloud-vla:8000 \ | ||
| --cloud-fallback-prefer cloud |
|
|
||
| - **`prefer="edge"` (default)**: Always run locally; use cloud only if edge crashes. | ||
| - **`prefer="cloud"`**: Always try cloud first; fall back to edge on timeout/failure. | ||
| - **`prefer="auto"`**: Route based on cloud latency history and availability. | ||
|
|
|
|
||
| ### JSONL Recording | ||
|
|
||
| When enabled via `--record-dir`, the server writes one line per request to `record.jsonl`: |
| "status": "ready", | ||
| "model": "pi0", | ||
| "policy_slot": "prod", | ||
| "queue_depth": 0, | ||
| "deadlines_missed": 0, |
There was a problem hiding this comment.
@copilot apply changes based on this feedback
There was a problem hiding this comment.
Already addressed in commit 061f4c0. The /health response example now matches the current handler implementation with fields like status, state, model_loaded, inference_mode, export_dir, vlm_loaded, consecutive_crashes, max_consecutive_crashes, and robot_id.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/FastCrest/reflex-vla/sessions/c8adea7e-fc90-4e2e-a578-7efd452b16ee Co-authored-by: segundavid-dev <117485200+segundavid-dev@users.noreply.github.com>
Agent-Logs-Url: https://github.com/FastCrest/reflex-vla/sessions/c8adea7e-fc90-4e2e-a578-7efd452b16ee Co-authored-by: segundavid-dev <117485200+segundavid-dev@users.noreply.github.com>
Agent-Logs-Url: https://github.com/FastCrest/reflex-vla/sessions/c8adea7e-fc90-4e2e-a578-7efd452b16ee Co-authored-by: segundavid-dev <117485200+segundavid-dev@users.noreply.github.com>
Agent-Logs-Url: https://github.com/FastCrest/reflex-vla/sessions/c8adea7e-fc90-4e2e-a578-7efd452b16ee Co-authored-by: segundavid-dev <117485200+segundavid-dev@users.noreply.github.com>
Agent-Logs-Url: https://github.com/FastCrest/reflex-vla/sessions/c8adea7e-fc90-4e2e-a578-7efd452b16ee Co-authored-by: segundavid-dev <117485200+segundavid-dev@users.noreply.github.com>
|
@copilot apply changes based on the comments in this thread |
All issues from the unresolved comment threads have already been addressed in commits 061f4c0 through b668b26:
No further changes needed. |
* fix: green main test suite — 3 prod bugs + 7 stale tests
Main has been red on `pytest CI` since today's v0.9.0 → v0.9.6 churn.
Diagnosed 3 real production bugs + 7 tests that drifted vs the live
CLI / API surface. Splits into:
PRODUCTION BUGS (these would have hit customers):
* `src/reflex/diagnostics/__init__.py` — `_ensure_registry_loaded()`
short-circuited on `if _REGISTRY:` which broke when any single
check_*.py was imported before run_all_checks (registry frozen at
one entry, 9 missing). Switched to a separate `_REGISTRY_LOADED`
bool flag.
* `src/reflex/diagnostics/check_rtc_chunks.py` — interpreted
`rtc_execution_horizon` as seconds and multiplied by frequency_hz,
over-counting by ~Hz×. Validator at embodiments/validate.py:163
documents the field as actions count. With Hz×over-count, every
preset (franka/so100/ur5) flagged "fail" at well-aligned chunk
sizes. Fixed: read field directly as int actions.
* `src/reflex/pro/license.py` — `issue_dev_license` wrote
license_version=2 (signed) with empty signature; loader rejected
the same file as corrupt. The whole dev-license escape hatch was
broken. Switched to LICENSE_VERSION_LEGACY_UNSIGNED so the loader's
unsigned path takes it.
STALE TESTS (drift vs current CLI/API):
* `test_doctor_diagnostics::TestSmoke` — derived expected check count
from the registry instead of hardcoding `== 10` so future check
additions don't break it.
* `test_cli_export_end_to_end::test_unsupported_model_type_raises` —
GR00T now matches the substring path; use a sentinel name.
* `test_install_smoke::test_import_reflex_version_is_v07` — used semver
parsing (>= 0.7.0) instead of `startswith("0.7.")`.
* `test_model_registry` — `--family openvla` now matches v0.9.6
registry; switched to a sentinel family. Output string changed from
"Available:" to "Available registry ids:".
* `test_export_mode::test_run_parallel_pi05_exports_*` — assert against
positional index 6 instead of [-1] after `per_step_expert` arg added.
* `test_vlm_prefix::TestOrchestratorFullPipeline` — `run()` now returns
(vlm_k, vlm_v) per-layer K/V tuple, not a single 3D prefix.
* `test_snapflow_backend` — 4 tests skip when `lerobot` not installed
(require [native]/[monolithic]/[rtc] extras, not in CI's [dev,onnx,serve].
Verified: 2441 passed, 51 skipped on Python 3.12 with the exact CI
extras (Obtaining file:///Users/romirjain/Desktop/building%20projects/reflex-vla
Installing build dependencies: started
Installing build dependencies: finished with status 'done'
Checking if build backend supports build_editable: started
Checking if build backend supports build_editable: finished with status 'done'
Getting requirements to build editable: started
Getting requirements to build editable: finished with status 'done'
Installing backend dependencies: started
Installing backend dependencies: finished with status 'done'
Preparing editable metadata (pyproject.toml): started
Preparing editable metadata (pyproject.toml): finished with status 'done'
Requirement already satisfied: cryptography>=42.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (46.0.3)
Requirement already satisfied: httpx>=0.24.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.28.1)
Requirement already satisfied: huggingface-hub>=0.20.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.36.2)
Requirement already satisfied: numpy>=1.24.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (2.2.6)
Requirement already satisfied: onnx>=1.15.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (1.21.0)
Requirement already satisfied: onnxscript>=0.1.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.6.2)
Requirement already satisfied: pydantic>=2.0.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (2.12.4)
Requirement already satisfied: pyyaml>=6.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (6.0.3)
Requirement already satisfied: rich>=13.0.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (15.0.0)
Requirement already satisfied: safetensors>=0.4.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.7.0)
Requirement already satisfied: torch>=2.1.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (2.10.0)
Requirement already satisfied: transformers<5.4,>=4.40 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (4.57.6)
Requirement already satisfied: typer>=0.9.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.20.0)
Requirement already satisfied: mypy>=1.10 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (1.19.1)
Requirement already satisfied: pytest-asyncio>=0.23 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (1.3.0)
Requirement already satisfied: pytest>=8.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (9.0.2)
Requirement already satisfied: ruff>=0.4.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.15.0)
Requirement already satisfied: onnxruntime>=1.17.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (1.24.4)
Requirement already satisfied: fastapi>=0.100.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.134.0)
Requirement already satisfied: jsonschema>=4.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (4.25.1)
Requirement already satisfied: pillow>=10.0.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (11.3.0)
Requirement already satisfied: prometheus-client>=0.19.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.24.1)
Requirement already satisfied: uvicorn>=0.23.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from reflex-vla==0.9.6) (0.41.0)
Requirement already satisfied: filelock in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from transformers<5.4,>=4.40->reflex-vla==0.9.6) (3.25.0)
Requirement already satisfied: packaging>=20.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from transformers<5.4,>=4.40->reflex-vla==0.9.6) (25.0)
Requirement already satisfied: regex!=2019.12.17 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from transformers<5.4,>=4.40->reflex-vla==0.9.6) (2026.2.19)
Requirement already satisfied: requests in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from transformers<5.4,>=4.40->reflex-vla==0.9.6) (2.32.5)
Requirement already satisfied: tokenizers<=0.23.0,>=0.22.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from transformers<5.4,>=4.40->reflex-vla==0.9.6) (0.22.2)
Requirement already satisfied: tqdm>=4.27 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from transformers<5.4,>=4.40->reflex-vla==0.9.6) (4.67.1)
Requirement already satisfied: fsspec>=2023.5.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from huggingface-hub>=0.20.0->reflex-vla==0.9.6) (2026.2.0)
Requirement already satisfied: hf-xet<2.0.0,>=1.1.3 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from huggingface-hub>=0.20.0->reflex-vla==0.9.6) (1.4.3)
Requirement already satisfied: typing-extensions>=3.7.4.3 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from huggingface-hub>=0.20.0->reflex-vla==0.9.6) (4.15.0)
Requirement already satisfied: cffi>=2.0.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from cryptography>=42.0->reflex-vla==0.9.6) (2.0.0)
Requirement already satisfied: pycparser in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from cffi>=2.0.0->cryptography>=42.0->reflex-vla==0.9.6) (2.23)
Requirement already satisfied: starlette>=0.46.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from fastapi>=0.100.0->reflex-vla==0.9.6) (0.52.1)
Requirement already satisfied: typing-inspection>=0.4.2 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from fastapi>=0.100.0->reflex-vla==0.9.6) (0.4.2)
Requirement already satisfied: annotated-doc>=0.0.2 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from fastapi>=0.100.0->reflex-vla==0.9.6) (0.0.4)
Requirement already satisfied: anyio in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from httpx>=0.24.0->reflex-vla==0.9.6) (4.12.1)
Requirement already satisfied: certifi in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from httpx>=0.24.0->reflex-vla==0.9.6) (2025.11.12)
Requirement already satisfied: httpcore==1.* in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from httpx>=0.24.0->reflex-vla==0.9.6) (1.0.9)
Requirement already satisfied: idna in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from httpx>=0.24.0->reflex-vla==0.9.6) (3.11)
Requirement already satisfied: h11>=0.16 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from httpcore==1.*->httpx>=0.24.0->reflex-vla==0.9.6) (0.16.0)
Requirement already satisfied: attrs>=22.2.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from jsonschema>=4.0->reflex-vla==0.9.6) (25.4.0)
Requirement already satisfied: jsonschema-specifications>=2023.03.6 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from jsonschema>=4.0->reflex-vla==0.9.6) (2025.9.1)
Requirement already satisfied: referencing>=0.28.4 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from jsonschema>=4.0->reflex-vla==0.9.6) (0.37.0)
Requirement already satisfied: rpds-py>=0.7.1 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from jsonschema>=4.0->reflex-vla==0.9.6) (0.30.0)
Requirement already satisfied: mypy_extensions>=1.0.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from mypy>=1.10->reflex-vla==0.9.6) (1.1.0)
Requirement already satisfied: pathspec>=0.9.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from mypy>=1.10->reflex-vla==0.9.6) (1.0.4)
Requirement already satisfied: librt>=0.6.2 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from mypy>=1.10->reflex-vla==0.9.6) (0.8.0)
Requirement already satisfied: protobuf>=4.25.1 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from onnx>=1.15.0->reflex-vla==0.9.6) (6.33.5)
Requirement already satisfied: ml_dtypes>=0.5.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from onnx>=1.15.0->reflex-vla==0.9.6) (0.5.4)
Requirement already satisfied: flatbuffers in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from onnxruntime>=1.17.0->reflex-vla==0.9.6) (25.12.19)
Requirement already satisfied: sympy in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from onnxruntime>=1.17.0->reflex-vla==0.9.6) (1.14.0)
Requirement already satisfied: onnx_ir<2,>=0.1.15 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from onnxscript>=0.1.0->reflex-vla==0.9.6) (0.2.0)
Requirement already satisfied: annotated-types>=0.6.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from pydantic>=2.0.0->reflex-vla==0.9.6) (0.6.0)
Requirement already satisfied: pydantic-core==2.41.5 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from pydantic>=2.0.0->reflex-vla==0.9.6) (2.41.5)
Requirement already satisfied: iniconfig>=1.0.1 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from pytest>=8.0->reflex-vla==0.9.6) (2.3.0)
Requirement already satisfied: pluggy<2,>=1.5 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from pytest>=8.0->reflex-vla==0.9.6) (1.5.0)
Requirement already satisfied: pygments>=2.7.2 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from pytest>=8.0->reflex-vla==0.9.6) (2.19.2)
Requirement already satisfied: markdown-it-py>=2.2.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from rich>=13.0.0->reflex-vla==0.9.6) (4.0.0)
Requirement already satisfied: mdurl~=0.1 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from markdown-it-py>=2.2.0->rich>=13.0.0->reflex-vla==0.9.6) (0.1.2)
Requirement already satisfied: mpmath<1.4,>=1.1.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from sympy->onnxruntime>=1.17.0->reflex-vla==0.9.6) (1.3.0)
Requirement already satisfied: setuptools in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from torch>=2.1.0->reflex-vla==0.9.6) (80.9.0)
Requirement already satisfied: networkx>=2.5.1 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from torch>=2.1.0->reflex-vla==0.9.6) (3.6.1)
Requirement already satisfied: jinja2 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from torch>=2.1.0->reflex-vla==0.9.6) (3.1.6)
Requirement already satisfied: click>=8.0.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from typer>=0.9.0->reflex-vla==0.9.6) (8.1.8)
Requirement already satisfied: shellingham>=1.3.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from typer>=0.9.0->reflex-vla==0.9.6) (1.5.4)
Requirement already satisfied: MarkupSafe>=2.0 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from jinja2->torch>=2.1.0->reflex-vla==0.9.6) (3.0.3)
Requirement already satisfied: charset_normalizer<4,>=2 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from requests->transformers<5.4,>=4.40->reflex-vla==0.9.6) (3.4.4)
Requirement already satisfied: urllib3<3,>=1.21.1 in /Users/romirjain/anaconda3/lib/python3.13/site-packages (from requests->transformers<5.4,>=4.40->reflex-vla==0.9.6) (2.6.1)
Building wheels for collected packages: reflex-vla
Building editable for reflex-vla (pyproject.toml): started
Building editable for reflex-vla (pyproject.toml): finished with status 'done'
Created wheel for reflex-vla: filename=reflex_vla-0.9.6-py3-none-any.whl size=21769 sha256=fa814e4a5e66c9d88ce465ed5b542b313eaaa2c214e095809def12757cb46c2f
Stored in directory: /private/var/folders/0m/9x1qvrkn179c6cpstxkqxcn80000gn/T/pip-ephem-wheel-cache-59ob5rns/wheels/30/e8/90/06fbe50a9d826022f91f9fe36795a7a533865706fc0f193102
Successfully built reflex-vla
Installing collected packages: reflex-vla
Attempting uninstall: reflex-vla
Found existing installation: reflex-vla 0.1.0
Uninstalling reflex-vla-0.1.0:
Successfully uninstalled reflex-vla-0.1.0
Successfully installed reflex-vla-0.9.6). All 6 unblocked-by-CI
PRs (#105, #107, #109) should turn green on the next run.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)
* fix: force COLUMNS=200 in conftest so help-output tests survive CI
Six CLI --help tests (test_cli, test_cuda_graphs, test_distill_cli,
test_one_command_deploy, test_runtime_calibration) failed on Ubuntu
CI runners but passed locally with identical rich/click/typer
versions. Root cause: GitHub Actions runners default to a terminal
width where Rich elides long option names to "--..." in the rendered
panel, breaking substring assertions like
`"--export-mode" in result.output`.
Set COLUMNS=200 in pytest_configure so every CliRunner invocation
gets a wide-enough rendering window. This is the long-term fix —
every future help-output test inherits it without needing per-test
ENV management.
Verified: 2441 passed locally on Py3.12 with CI's exact extras.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: set TERM=dumb in conftest so CI's color renderer doesn't break flag matching
Reproduced under `CI=true GITHUB_ACTIONS=true`: Rich inserts ANSI color
escapes BETWEEN the two `-` chars of long flag names, so substring
assertions like `"--export-mode" in result.output` are False even
though the rendered help looks identical. The two hyphens are no
longer adjacent in the captured buffer.
The conftest's earlier `COLUMNS=200` fix removed Rich's name-elision
("--..." truncation) but didn't address this second behavior. Adding
`TERM=dumb` forces Rich into no-color plain-text rendering — flag
names render as adjacent `--name` and substring search works.
Verified locally with CI=true GITHUB_ACTIONS=true forced: 2441 passed,
51 skipped (matches the no-CI-env run).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Description
Adds comprehensive documentation for 'The Wedge' — the server's unique composition pattern combining Safety, Split, Adaptive, and Deadline wedges. This explains how each wedge independently enforces safety constraints, handles cloud failover, optimizes latency, and guarantees response deadlines.
Type of Change
How Has This Been Tested?
This is a documentation-only change. No functional code changes.
reflex serve --helpoutputChecklist