Deploy PolyGuard workbench from master

.gitattributes

@@ -42,3 +42,18 @@ docs/results/submission_evidence/qwen_0_5b_1_5b_3b/reward_component_bars.png fil
 docs/results/submission_evidence_qwen_0_5b_1_5b/charts/generated/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
 docs/results/submission_evidence_qwen_0_5b_1_5b_3b/charts/generated/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
 submission_bundle/qwen_completed_runs/charts/generated/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
+docs/UI[[:space:]]Images/1.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/UI[[:space:]]Images/2.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/UI[[:space:]]Images/3.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/UI[[:space:]]Images/4.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/UI[[:space:]]Images/5.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/assets/diagrams/data_training_pipeline.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/diagrams/deployment_topology.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/diagrams/frontend_runtime_surface.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/diagrams/multi_agent_orchestration.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/diagrams/reward_decomposition.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/diagrams/system_architecture.png filter=lfs diff=lfs merge=lfs -text
+docs/results/final_submission_evidence/charts/curated/reward_and_safety/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
+docs/results/final_submission_evidence/charts/curated/training/qwen_3b_grpo_reward_curve.png filter=lfs diff=lfs merge=lfs -text
+docs/results/final_submission_evidence/charts/frontpage/04_reward_components.png filter=lfs diff=lfs merge=lfs -text
+docs/results/final_submission_evidence/charts/frontpage/09_qwen_3b_grpo_reward_curve.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -27,3 +27,5 @@ data/retrieval_index/*
 !data/**/.gitkeep
 app/ui/frontend/.vite/
 /demo.md
+docs/hf_blog_draft.md
+docs/submission_gap_review.md

Dockerfile

@@ -1,6 +1,6 @@
-# Hugging Face Space: nginx on PORT (7860) + OpenEnv (8100) + API (8200) + Vite-built UI.
-# Build: docker build -t polyguard-space .
-# HF Spaces use this file by default when "Dockerfile path" is unset — keep this as the demo image.
+# Hugging Face Space: single-port edge (nginx) + OpenEnv (8100) + API (8200) + static UI.
+# Build from repository root: docker build -f Dockerfile.space -t polyguard-space .
+# Cheap tier: use Space "CPU basic"; first boot downloads ~1.1GB model bundle.
 
 FROM node:20-bookworm-slim AS frontend
 WORKDIR /build

Dockerfile.space

@@ -1,5 +1,6 @@
-# Same image as ./Dockerfile — use this path in HF Space settings if "Dockerfile path"
-# must be explicit (e.g. Dockerfile.space). Keep in sync with Dockerfile.
+# Hugging Face Space: single-port edge (nginx) + OpenEnv (8100) + API (8200) + static UI.
+# Build from repository root: docker build -f Dockerfile.space -t polyguard-space .
+# Cheap tier: use Space "CPU basic"; first boot downloads ~1.1GB model bundle.
 
 FROM node:20-bookworm-slim AS frontend
 WORKDIR /build

README.md

@@ -1,5 +1,5 @@
 ---
-title: PolyGuard OpenEnv
+title: PolyGuard OpenEnv Workbench
 colorFrom: blue
 colorTo: green
 sdk: docker
@@ -14,10 +14,20 @@ Run all CLI commands from this directory (`cd polyguard-rl`). The repository roo
 ## Submission Links
 
 - GitHub Repo URL: [https://github.com/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK](https://github.com/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK)
-- HF Space URL: [https://huggingface.co/spaces/TheJackBright/polyguard-openenv](https://huggingface.co/spaces/TheJackBright/polyguard-openenv)
+- HF Space URL: [https://huggingface.co/spaces/TheJackBright/polyguard-openenv-workbench](https://huggingface.co/spaces/TheJackBright/polyguard-openenv-workbench)
 - Colab Notebook URL: [https://colab.research.google.com/github/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK/blob/master/polyguard-rl/PolyGuard_SFT_GRPO_One_Run_Runner.ipynb](https://colab.research.google.com/github/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK/blob/master/polyguard-rl/PolyGuard_SFT_GRPO_One_Run_Runner.ipynb) (see also `notebooks/09_training_loop.ipynb` for a modular training walkthrough)
-- YouTube Video URL: not used for this submission; see Hugging Face Blog URL below.
-- Hugging Face Blog URL: [https://huggingface.co/blog/TheJackBright/polyguard-openenv](https://huggingface.co/blog/TheJackBright/polyguard-openenv) *(publish `docs/hf_blog_draft.md` or replace with a live story URL)*
+- YouTube Video URL: not used for this submission; the repository root README is the story artifact.
+- Story artifact: the repository root [`README.md`](../README.md) is the final blog-style narrative and evidence map.
+
+## Shared Environment, Logs, And Scripts
+
+The required environment files, training logs, and training scripts are shared
+in the repo and indexed in [Submission Artifact Index](docs/submission_artifacts.md).
+
+- Environment/runtime: `openenv.yaml`, `pyproject.toml`, `uv.lock`, `requirements*.txt`, `Dockerfile*`, `app/env/`, `server/app.py`, and `app/hf_space/Dockerfile`.
+- Training scripts/notebooks: `PolyGuard_SFT_GRPO_One_Run_Runner.ipynb`, `notebooks/09_training_loop.ipynb`, `scripts/train_sft_trl.py`, `scripts/train_grpo_trl.py`, `scripts/deploy_training_space.py`, `app/hf_space/training_runner.py`, and `app/training/`.
+- Training logs/results: `docs/results/final_submission_evidence/reports/`, `docs/results/sweeps/`, `docs/results/submission_evidence_qwen_0_5b_1_5b_3b/reports/`, and `docs/results/qwen_completed_runs/reports/`.
+- Final downloadable artifact Space: [https://huggingface.co/spaces/adithya9903/polyguard-openenv-final-artifacts](https://huggingface.co/spaces/adithya9903/polyguard-openenv-final-artifacts).
 
 ## Problem Statement
 
@@ -41,8 +51,18 @@ Thirteen verifier-backed reward components roll up into four primary channels (`
 
 ## Training And Post-Training Strategy
 
-Build corpora (`scripts/bootstrap_data.py`, `scripts/build_training_corpus.py`), SFT with TRL (`scripts/train_sft_trl.py`), GRPO with environment reward (`scripts/train_grpo_trl.py`), merge adapters (`scripts/merge_adapters_safe.py`), validate inference (`scripts/test_inference_postsave.py`), evaluate and plot (`scripts/evaluate_*.py`, `docs/results/`). Optional HF GPU training: `scripts/deploy_training_space.py`. Full commands: repository root [`README.md`](../README.md) or `docs/training.md`.
+Build corpora (`scripts/bootstrap_data.py`, `scripts/build_training_corpus.py`), SFT with TRL (`scripts/train_sft_trl.py`), GRPO with environment reward (`scripts/train_grpo_trl.py`), merge adapters (`scripts/merge_adapters_safe.py`), validate inference (`scripts/test_inference_postsave.py`), evaluate and plot (`scripts/evaluate_*.py`, `docs/results/`). Optional HF GPU training uses `scripts/deploy_training_space.py`; public review should start with the repository root [`README.md`](../README.md), then `docs/training.md` for implementation notes.
 
 ## Documentation index
 
-- [Architecture](docs/architecture.md) · [Environment](docs/environment_design.md) · [Rewards](docs/reward_design.md) · [Training](docs/training.md) · [Evaluation](docs/evaluation.md) · [Deployment](docs/deployment.md) · [Datasets](docs/datasets.md) · [Participant guide traceability](docs/participant_guide_traceability.md) · [Idea doc vs implementation](docs/idea_document_traceability.md) · [**Space UI demo script**](docs/DEMO_RECORDING_SCRIPT.md)
+- [Architecture](docs/architecture.md)
+- [Environment](docs/environment_design.md)
+- [Rewards](docs/reward_design.md)
+- [Training](docs/training.md)
+- [Evaluation](docs/evaluation.md)
+- [Deployment](docs/deployment.md)
+- [Datasets](docs/datasets.md)
+- [Participant guide traceability](docs/participant_guide_traceability.md)
+- [Idea doc vs implementation](docs/idea_document_traceability.md)
+- [Submission artifact index](docs/submission_artifacts.md)
+- [**Space UI demo script**](docs/DEMO_RECORDING_SCRIPT.md)

README_HF_SPACE.md

@@ -1,12 +0,0 @@
----
-title: PolyGuard OpenEnv
-emoji: 🛡️
-colorFrom: blue
-colorTo: purple
-sdk: docker
-app_port: 7860
-pinned: false
-license: mit
----
-
-Full-stack **PolyGuard** workbench: OpenEnv (WebSocket), FastAPI, and React UI behind nginx on `PORT`. Uses **CPU basic**; first cold start downloads the public [usable model bundle](https://huggingface.co/TheJackBright/polyguard-openenv-training-full-artifacts/tree/main/usable_model_bundles/local-qwen-0-5b-active-smoke) (~1.1 GB). See `docker/space/README.md` for details.

app/ui/frontend/dist/assets/index-DV0STDGE.css

@@ -1 +0,0 @@
-@import"https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@500;700&family=Space+Grotesk:wght@500;600;700&display=swap";:root{--bg: #03030b;--surface: rgba(13, 16, 35, .62);--surface-2: rgba(19, 24, 51, .58);--surface-3: rgba(35, 26, 72, .68);--ink: #f6f7ff;--muted: #a6a9c8;--line: rgba(197, 187, 255, .22);--line-soft: rgba(189, 178, 255, .14);--accent: #9b7cff;--accent-2: #28e8ff;--accent-3: #ff4fd8;--warning: #d29922;--critical: #f85149;--glass: rgba(8, 11, 25, .58);--shadow: 0 24px 80px rgba(0, 0, 0, .42), inset 0 1px 0 rgba(255, 255, 255, .08);--glow: 0 0 34px rgba(155, 124, 255, .22), 0 0 64px rgba(40, 232, 255, .08);color-scheme:dark}*{box-sizing:border-box}html,body,#root{margin:0;min-height:100%;background:var(--bg);color:var(--ink);font-family:IBM Plex Sans,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif}body{min-width:320px;overflow-x:hidden;background:radial-gradient(circle at 50% -10%,rgba(106,68,255,.28),transparent 34rem),radial-gradient(circle at 85% 12%,rgba(255,79,216,.12),transparent 30rem),#02020a}button,select,input{min-height:40px;border:1px solid var(--line);border-radius:14px;background:#080b1bc7;color:var(--ink);font:inherit}button{width:auto;padding:9px 14px;background:linear-gradient(180deg,rgba(255,255,255,.22),transparent),linear-gradient(135deg,var(--accent),var(--accent-2));border-color:transparent;color:#030414;font-weight:700;cursor:pointer;box-shadow:0 10px 30px #5b5cff52,inset 0 0 18px #ffffff2e;transition:background .14s ease,border-color .14s ease,box-shadow .14s ease,transform .12s ease}button:hover:not(:disabled){background:linear-gradient(180deg,rgba(255,255,255,.28),transparent),linear-gradient(135deg,#b49bff,#5ef5ff);box-shadow:0 14px 44px #28e8ff42,inset 0 0 22px #ffffff38;transform:translateY(-1px)}button.secondary,.mode-toggle button{background:#9b7cff1f;border-color:#9b7cff4d;color:var(--accent);box-shadow:inset 0 0 16px #bf97ff1f}button.secondary:hover:not(:disabled),.mode-toggle button:hover:not(:disabled){background:#9b7cff33}button:disabled{cursor:not-allowed;opacity:.48;transform:none}select,input{width:100%;padding:8px 11px;-webkit-backdrop-filter:blur(12px);backdrop-filter:blur(12px)}select{color-scheme:dark}select:focus,input:focus,button:focus{outline:2px solid rgba(40,232,255,.38);outline-offset:2px}pre{margin:0;max-height:260px;overflow:auto;font-family:JetBrains Mono,ui-monospace,SFMono-Regular,Menlo,Monaco,monospace;font-size:.76rem;line-height:1.55;white-space:pre-wrap;word-break:break-word}table{width:100%;border-collapse:collapse}th,td{padding:8px 10px;border-bottom:1px solid var(--line-soft);text-align:left;font-size:.84rem}.workbench-shell{position:relative;min-height:100vh;isolation:isolate;overflow:hidden;padding:20px;background:linear-gradient(180deg,#090b2338,#03030be0 44rem),var(--bg)}.workbench-container{position:relative;z-index:2;width:min(1440px,100%);margin:0 auto}.metaverse-backdrop{position:fixed;top:0;right:0;bottom:0;left:0;z-index:0;overflow:hidden;pointer-events:none}.blackhole-video{position:absolute;top:-32vh;left:50%;width:min(1300px,148vw);min-width:760px;height:74vh;opacity:.78;mix-blend-mode:screen;object-fit:cover;transform:translate(-50%) rotate(180deg);filter:saturate(1.18) contrast(1.08)}.stars-canvas{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;opacity:.86}.stars-canvas canvas{display:block}.nebula-orb{position:absolute;border-radius:999px;filter:blur(18px);mix-blend-mode:screen}.orb-one{right:-8rem;top:14rem;width:28rem;height:28rem;background:radial-gradient(circle,rgba(255,79,216,.24),transparent 68%)}.orb-two{left:-10rem;bottom:0;width:34rem;height:34rem;background:radial-gradient(circle,rgba(40,232,255,.18),transparent 70%)}.nebula-grid{position:absolute;top:0;right:0;bottom:0;left:0;background-image:linear-gradient(rgba(255,255,255,.035) 1px,transparent 1px),linear-gradient(90deg,rgba(255,255,255,.035) 1px,transparent 1px);background-size:72px 72px;-webkit-mask-image:linear-gradient(to bottom,transparent,black 18%,transparent 86%);mask-image:linear-gradient(to bottom,transparent,black 18%,transparent 86%);opacity:.36;transform:perspective(900px) rotateX(60deg) translateY(12rem);transform-origin:center bottom}.cosmic-vignette{position:absolute;top:0;right:0;bottom:0;left:0;z-index:2;background:radial-gradient(circle at 50% 0%,transparent 0,rgba(3,3,11,.1) 26rem,rgba(3,3,11,.86) 62rem),linear-gradient(180deg,#03030b0a,#03030be6 76%)}.metaverse-hero{position:relative;display:grid;grid-template-columns:minmax(0,1.3fr) minmax(300px,.72fr);align-items:end;gap:22px;margin:18px 0 14px;overflow:hidden;padding:28px}.metaverse-hero:before{content:"";position:absolute;top:-1px;right:-1px;bottom:-1px;left:-1px;z-index:-1;background:radial-gradient(circle at 16% 10%,rgba(155,124,255,.26),transparent 28rem),radial-gradient(circle at 80% 0%,rgba(40,232,255,.18),transparent 24rem)}.hero-copy{min-width:0}.welcome-box{display:inline-flex;align-items:center;width:max-content;max-width:100%;gap:9px;isolation:isolate;overflow:hidden;margin-bottom:18px;border:1px solid rgba(185,157,255,.45);border-radius:999px;padding:8px 12px;background:#712fff1a;box-shadow:inset 0 -7px 11px #a48fff1f,0 0 28px #9b7cff24;-webkit-backdrop-filter:blur(10px);backdrop-filter:blur(10px)}.spark-glyph,.welcome-text{color:var(--accent);font-size:.78rem;font-weight:900;letter-spacing:.12em;text-transform:uppercase}.welcome-text{background:linear-gradient(0deg,#ffffff6b,#ffffff6b),linear-gradient(90deg,#e59cff,#ba9cff 48%,#8ff6ff);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}.metaverse-hero h2{max-width:900px;margin:0;color:var(--ink);font-family:Space Grotesk,IBM Plex Sans,system-ui,sans-serif;font-size:clamp(2.4rem,6vw,5.7rem);line-height:.92;letter-spacing:-.07em}.metaverse-hero h2 span{display:inline;background:linear-gradient(90deg,#b49bff,#5ef5ff 52%,#ff7ce7);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}.metaverse-hero p{max-width:760px;margin:18px 0 0;color:#c5c8df;font-size:1rem;line-height:1.7}.hero-stat-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:10px}.hero-stat-grid div{min-width:0;border:1px solid var(--line-soft);border-radius:18px;background:#090d1f8f;padding:14px;box-shadow:inset 0 1px #ffffff14;-webkit-backdrop-filter:blur(16px);backdrop-filter:blur(16px)}.hero-stat-grid span{display:block;color:var(--muted);font-size:.7rem;font-weight:900;letter-spacing:.08em;text-transform:uppercase}.hero-stat-grid strong{display:block;margin-top:7px;overflow:hidden;color:var(--ink);font-family:Space Grotesk,IBM Plex Sans,sans-serif;font-size:1.05rem;text-overflow:ellipsis;white-space:nowrap}.panel-surface,.panel{border:1px solid var(--line);border-radius:24px;background:var(--surface);box-shadow:var(--shadow);backdrop-filter:blur(22px) saturate(1.25);-webkit-backdrop-filter:blur(22px) saturate(1.25)}.topbar{display:grid;grid-template-columns:minmax(220px,1fr) auto auto minmax(320px,.9fr);align-items:center;gap:14px;padding:16px}.title-wrap{min-width:0}.title-wrap h1,.page h1{margin:0;color:var(--ink);font-family:Space Grotesk,IBM Plex Sans,sans-serif;font-size:1.5rem;line-height:1.1;font-weight:800;letter-spacing:-.04em}.title-wrap p,.muted{margin:4px 0 0;color:var(--muted);font-size:.88rem}.mode-toggle{display:grid;grid-template-columns:repeat(2,minmax(126px,1fr));gap:6px;padding:4px;border:1px solid var(--line);border-radius:18px;background:#050814b3;box-shadow:inset 0 0 24px #9b7cff14}.mode-toggle button{min-height:34px;padding:6px 10px;border-radius:14px;box-shadow:none}.mode-toggle button.active{background:linear-gradient(135deg,var(--accent),var(--accent-2));color:#030414;box-shadow:0 10px 28px #28e8ff2e}.topbar-status,.topbar-actions,.button-row{display:flex;align-items:center;justify-content:flex-end;flex-wrap:wrap;gap:8px}.topbar-actions{display:grid;grid-template-columns:minmax(170px,1fr) auto}.qtip-trigger{min-height:32px;padding:6px 11px}.status-chip,.panel-heading span,.med-card-header span{display:inline-flex;align-items:center;min-height:28px;border:1px solid var(--line);border-radius:999px;padding:4px 10px;background:#0c1023b8;color:var(--muted);font-size:.72rem;font-weight:800;letter-spacing:.04em;text-transform:uppercase;white-space:nowrap}.status-chip.live{border-color:#28e8ff70;background:#28e8ff1f;color:#78f6ff;box-shadow:0 0 18px #28e8ff24}.status-chip.idle{border-color:#9aa6b247}.advanced-strip{display:grid;grid-template-columns:minmax(160px,.4fr) minmax(260px,1fr);gap:12px;margin-top:12px;padding:14px}.model-truth{margin-top:12px;padding:14px}.model-truth.verified{border-color:#28e8ff80}.model-truth.unverified{border-color:#ffd35c70}.model-truth p{margin:0 0 12px;color:var(--muted);font-size:.88rem;line-height:1.5}.model-truth-grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px}.model-truth-grid div{min-width:0;border:1px solid var(--line-soft);border-radius:18px;background:var(--surface-2);padding:10px}.model-truth-grid span{color:var(--muted);font-size:.7rem;font-weight:800;letter-spacing:.05em;text-transform:uppercase}.model-truth-grid strong{display:block;margin-top:5px;color:var(--ink);font-size:.86rem;line-height:1.35;overflow-wrap:anywhere}.field{display:flex;min-width:0;flex-direction:column;gap:6px}.field span,.kpi-grid span,.action-detail-grid span,.compact-defs dt{color:var(--muted);font-size:.72rem;font-weight:800;letter-spacing:.05em;text-transform:uppercase}.workbench-layout{display:grid;grid-template-columns:minmax(320px,1.05fr) minmax(320px,.95fr);gap:16px;margin-top:16px;align-items:start}.panel-wide{grid-column:1 / -1}.panel-scroll{min-height:348px;padding:16px}.panel-heading{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-bottom:12px}.inline-heading{margin-bottom:10px}.panel-heading h2,.panel h3,.history-grid h2{margin:0;color:#d8d6ff;font-family:Space Grotesk,IBM Plex Sans,sans-serif;font-size:.82rem;font-weight:800;letter-spacing:.08em;text-transform:uppercase}.panel-surface:not(.topbar,.advanced-strip,.metaverse-hero){padding:16px}.kpi-grid,.action-detail-grid{display:grid;grid-template-columns:repeat(4,minmax(120px,1fr));gap:10px}.kpi-grid div,.action-detail-grid div{min-width:0;min-height:72px;border:1px solid var(--line-soft);border-radius:18px;background:var(--surface-2);padding:12px;box-shadow:inset 0 1px #ffffff0f}.kpi-grid strong,.action-detail-grid strong,.compact-defs dd{display:block;margin-top:6px;color:var(--ink);font-family:Space Grotesk,IBM Plex Sans,sans-serif;font-size:.96rem;line-height:1.25;overflow-wrap:anywhere}.overview-lower{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin-top:16px}.overview-lower h3{margin:0 0 8px;color:var(--muted);font-size:.78rem;letter-spacing:.05em;text-transform:uppercase}.compact-defs{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px;margin:0}.compact-defs div{min-width:0;border:1px solid var(--line-soft);border-radius:16px;background:#080c1d9e;padding:10px}.compact-defs dd{margin-left:0;font-size:.86rem}.candidate-list,.history-list,.reward-bars,.event-log{display:flex;flex-direction:column;gap:8px;max-height:292px;overflow:auto;padding-right:2px}.candidate-row{display:grid;grid-template-columns:minmax(150px,1fr) minmax(90px,.65fr) 64px;width:100%;min-height:58px;align-items:center;gap:8px;border-color:var(--line-soft);background:var(--surface-2);color:var(--ink);text-align:left;box-shadow:none}.candidate-row:hover:not(:disabled){border-color:#28e8ff52;background:var(--surface-3);box-shadow:inset 0 0 24px #28e8ff14}.candidate-row.selected{border-color:#28e8ffb8;background:linear-gradient(90deg,#28e8ff29,#9b7cff14),#0b1023b8;box-shadow:inset 3px 0 0 var(--accent-2),0 0 26px #28e8ff1a}.candidate-row.illegal{border-color:#ffd35c38;background:#221b317a;color:#f6f7ff94}.candidate-row.illegal strong{color:#f7d878}.candidate-row span{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.candidate-row strong{display:block;color:#90f8ff;font-size:.82rem}.action-console{min-height:348px}.action-detail-grid{grid-template-columns:repeat(2,minmax(0,1fr));margin-bottom:12px}.action-console .field{margin-bottom:10px}.console-notice{margin:0 0 12px;border:1px solid rgba(255,211,92,.34);border-radius:16px;background:#ffd35c1a;color:#f7d878;padding:10px 12px;font-size:.84rem;line-height:1.45}.console-notice strong{color:#fff4b8}.button-row{justify-content:flex-start}.reward-row{display:grid;grid-template-columns:minmax(150px,.9fr) minmax(110px,1fr) 56px;align-items:center;gap:8px;font-size:.8rem}.reward-row span{min-width:0;overflow:hidden;color:var(--muted);text-overflow:ellipsis;white-space:nowrap}.reward-row strong{color:var(--ink);font-family:JetBrains Mono,ui-monospace,monospace;font-size:.76rem;text-align:right}.reward-track{height:7px;overflow:hidden;border-radius:999px;background:#040712db}.reward-fill{height:100%;border-radius:inherit;background:linear-gradient(90deg,var(--accent-3),var(--accent),var(--accent-2));box-shadow:0 0 16px #28e8ff5c;transition:width .22s ease}.med-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:10px}.med-card{min-width:0;border:1px solid var(--line-soft);border-radius:18px;background:var(--surface-2);padding:12px;box-shadow:inset 0 1px #ffffff0f}.med-card.high-risk{border-color:#ff4fd86b;box-shadow:0 0 22px #ff4fd814,inset 0 1px #ffffff0f}.med-card-header{display:flex;align-items:center;justify-content:space-between;gap:8px}.med-card-header strong{min-width:0;overflow:hidden;color:var(--ink);text-overflow:ellipsis;white-space:nowrap}.med-card-header span{border-color:#ff4fd86b;background:#ff4fd81f;color:#ff9dea;font-size:.64rem}.med-card p,.med-meta{margin:6px 0 0;color:var(--muted);font-size:.84rem}.med-meta{display:flex;flex-wrap:wrap;gap:8px}.med-meta span{color:#8ff6ff}.history-grid{display:grid;grid-template-columns:1fr 1fr;gap:16px}.history-item,.event-log div{border:1px solid var(--line-soft);border-radius:16px;background:var(--surface-2);padding:10px 12px;color:var(--ink);font-size:.84rem;overflow-wrap:anywhere}.history-item strong{display:block;margin-bottom:4px}.history-item span{color:var(--muted)}.history-item.warning{border-color:#d2992252;color:#f0c36a}.detail-panel{min-height:220px}.event-panel{margin-bottom:22px}.event-log{max-height:210px;font-family:JetBrains Mono,ui-monospace,monospace}.error-banner{margin-bottom:10px;border:1px solid rgba(248,81,73,.36);border-radius:16px;background:#f851491f;color:#ff8b85;padding:10px 12px;font-weight:800}.qtip-overlay{position:fixed;top:0;right:0;bottom:0;left:0;z-index:1000;pointer-events:none}.qtip-dim{position:absolute;top:0;right:0;bottom:0;left:0;background:#03030bb8;-webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px);pointer-events:auto}.qtip-ring{position:fixed;z-index:1001;border:2px solid var(--accent-2);border-radius:20px;box-shadow:0 0 0 4px #28e8ff29,0 0 38px #28e8ff4d;pointer-events:none;transition:top .18s ease,left .18s ease,width .18s ease,height .18s ease}.qtip-card{position:fixed;top:var(--tip-top, 18px);left:var(--tip-left, 18px);z-index:1002;width:min(374px,calc(100vw - 28px));padding:18px;pointer-events:auto;animation:qtipIn .16s ease-out}.qtip-header{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:10px}.qtip-header span,.qtip-header strong{color:var(--accent);font-size:.72rem;font-weight:900;letter-spacing:.08em;text-transform:uppercase}.qtip-card h2{margin:0 0 8px;color:var(--ink);font-size:1.05rem;letter-spacing:0}.qtip-card p{margin:0;color:var(--muted);font-size:.9rem;line-height:1.55}.qtip-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:16px}@keyframes qtipIn{0%{opacity:0;transform:translateY(6px)}to{opacity:1;transform:translateY(0)}}.page{padding:20px}.grid,.grid-mini{display:grid;grid-template-columns:repeat(2,minmax(240px,1fr));gap:12px}.list{margin:0;padding-left:18px}.kpi{margin:0;font-size:1.6rem;font-weight:800}.hero-line{width:280px;max-width:100%;height:4px;margin:14px 0;border-radius:999px;background:linear-gradient(90deg,var(--accent),var(--accent-2))}.actions{display:flex;flex-wrap:wrap;gap:8px}@media (max-width: 1180px){.metaverse-hero{grid-template-columns:1fr}.topbar{grid-template-columns:1fr;align-items:stretch}.topbar-status,.topbar-actions{justify-content:flex-start}.workbench-layout,.overview-lower,.history-grid{grid-template-columns:1fr}.panel-wide{grid-column:auto}}@media (max-width: 760px){.workbench-shell{padding:10px}.blackhole-video{top:-20vh;min-width:620px;height:54vh}.metaverse-hero{margin-top:8px;padding:18px}.metaverse-hero h2{font-size:clamp(2rem,13vw,3.4rem);letter-spacing:-.055em}.hero-stat-grid{grid-template-columns:1fr}.topbar,.panel-surface:not(.topbar,.advanced-strip,.metaverse-hero),.advanced-strip{padding:12px}.mode-toggle,.topbar-actions,.advanced-strip,.model-truth-grid,.kpi-grid,.action-detail-grid,.compact-defs,.grid,.grid-mini{grid-template-columns:1fr}.topbar-actions button,.button-row button,.qtip-actions button{width:100%}.qtip-card{inset:auto 10px 14px 10px;width:auto}.qtip-actions{flex-direction:column}.qtip-ring{display:none}.candidate-row,.reward-row{grid-template-columns:1fr}.candidate-row span,.reward-row span{white-space:normal}.reward-row strong{text-align:left}.panel-scroll,.action-console,.detail-panel{min-height:auto}.candidate-list,.history-list,.reward-bars,.event-log{max-height:none}}::-webkit-scrollbar{width:7px;height:7px}::-webkit-scrollbar-track{background:transparent}::-webkit-scrollbar-thumb{border-radius:999px;background:#9aa6b257}

app/ui/frontend/dist/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>POLYGUARD-RL Workbench</title>
-    <script type="module" crossorigin src="/assets/index-DgY-oaWG.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DV0STDGE.css">
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>

checkpoints/README.md

@@ -1,23 +0,0 @@
-# Local checkpoints (not in Git)
-
-Trained weights live here so clones stay small. After cloning, install the published bundle:
-
-```bash
-cd polyguard-rl
-python scripts/install_hf_active_bundle.py
-```
-
-That creates **`active/`** with:
-
-| Path | Contents |
-|------|----------|
-| `active/active_model_manifest.json` | Which artifact to load (GRPO vs merged vs SFT) |
-| `active/grpo_adapter/` | PEFT GRPO adapter (+ tokenizer files) |
-| `active/merged/` | Full merged Qwen 0.5B weights (~1 GB) |
-| `active/sft_adapter/` | SFT LoRA fallback |
-
-A Hub cache copy may also appear under `.hf_bundles/` (safe to delete after a successful install).
-
-Enable in `.env`: `POLYGUARD_ENABLE_ACTIVE_MODEL=true` and `POLYGUARD_HF_MODEL=Qwen/Qwen2.5-0.5B-Instruct` (base for the adapter path).
-
-**If this folder looks empty in the editor:** run the install command above; then confirm with `ls active/`.

docker/space/README.md

@@ -12,24 +12,16 @@ Never commit or paste Hugging Face tokens into chat or the repo. If a token was
 
    ```bash
    cd polyguard-rl
-   docker build -t polyguard-space .
+   docker build -f Dockerfile.space -t polyguard-space .
    ```
 
-3. Push the Space repo. The root **`Dockerfile`** is the full demo (Vite UI + nginx + API + OpenEnv). Hugging Face uses it automatically when **Dockerfile path** is empty. If your Space was created earlier with a different Dockerfile, trigger **Factory reboot** after pushing so the new image builds.
+3. Push the Space repo (HF expects `Dockerfile` at root). Either:
 
-4. Commit and push to the Space repository. HF builds the image on their builders (you do not need to `docker push` to Docker Hub for standard Spaces).
-
-## FDA panel / latest UI missing on the live Space
-
-Pushing code to GitHub alone does **not** refresh `huggingface.co/spaces/...` unless that Space is connected to the same repo **and** rebuilds from the branch that has your UI (for example `fda` vs `main`). This repo’s usual demo path is **upload via Hub API**:
+   - **Option A:** In the Space repo on Hub, set **Build → Dockerfile path** to `Dockerfile.space` if the UI allows, **or** copy/rename: `cp Dockerfile.space Dockerfile` in the branch you push.
 
-```bash
-cd polyguard-rl
-export HF_TOKEN="hf_..."   # write token; never commit it
-uv run python scripts/deploy_space_api.py --repo-id TheJackBright/polyguard-openenv
-```
+   - **Option B:** Make this `polyguard-rl` folder the Space git root and add a symlink or duplicate `Dockerfile` pointing to the same content as `Dockerfile.space`.
 
-Wait for **Build** in the Space logs to finish, then use **Factory reboot** or a hard browser refresh if the page still looks old. **Dockerfile path** should be empty (default `Dockerfile`) or `Dockerfile` / `Dockerfile.space`. If the Space uses the **full monorepo** as its Git root, set Dockerfile path to the repo-root `Dockerfile` or to `polyguard-rl/Dockerfile`.
+4. Commit and push to the Space repository. HF builds the image on their builders (you do not need to `docker push` to Docker Hub for standard Spaces).
 
 ## Runtime
 

docs/DEMO_RECORDING_SCRIPT.md

@@ -12,7 +12,7 @@ Use this document while screen-recording the Hugging Face Space (or local Docker
 4. **Wait for cold start**: first load may download the model bundle (several minutes). The **Event Log** and **Model Truth** panel will tell you if the policy failed to load (heuristic fallback is still usable for env steps).
 5. **Optional**: hide mouse cursor in OBS if you prefer; otherwise move slowly and pause **2 seconds** on each panel after major clicks.
 
-**Primary Space (product):** `https://huggingface.co/spaces/TheJackBright/polyguard-openenv`  
+**Primary Space (product):** `https://huggingface.co/spaces/TheJackBright/polyguard-openenv-workbench`
 Runtime: nginx fronts the **product API** (default `8200`) and **OpenEnv service** (`8100`); see `docker/space/entrypoint.sh`.
 
 ---
@@ -391,7 +391,7 @@ Click **Q Tips** in the top bar. The app cycles **10 slides** (`App.tsx` → `GU
 **Say:** *“This patient block and risk delta come straight from the observation object.”*
 
 **Action:** **Candidate Actions** — click 2–3 rows; show **Blocked** vs legal. Select a **legal** row.  
-**Say:** *“Candidates are legal moves from the env; illegal rows are disabled .”*
+**Say:** *“Candidates are legal moves from the env; illegal rows are disabled.”*
 
 **Action:** **Action Console** — tweak **Confidence** and **Rationale** slightly. Click **Submit Candidate**.  
 **Say:** *“Submit Candidate hits `/env/step_candidate` with my chosen legal action, confidence, and rationale.”*

docs/deployment.md

@@ -24,13 +24,13 @@ The global `hf` command on this workstation currently fails because its installe
 ## Hugging Face Space Deployment
 
 ```bash
-export HF_SPACE_REPO_ID="TheJackBright/polyguard-openenv"
+export HF_SPACE_REPO_ID="TheJackBright/polyguard-openenv-workbench"
 uv run python scripts/deploy_space_api.py --repo-id "$HF_SPACE_REPO_ID"
 uv run python -c "from huggingface_hub import HfApi; print(HfApi().space_info('$HF_SPACE_REPO_ID').id)"
-openenv validate --url "https://thejackbright-polyguard-openenv.hf.space"
+openenv validate --url "https://thejackbright-polyguard-openenv-workbench.hf.space"
 ```
 
-`scripts/deploy_space_api.py` is the preferred deployment path for this repo because it uploads a valid Docker Space README frontmatter bundle through `huggingface_hub.HfApi`. `scripts/deploy_space.sh` remains available, but the current OpenEnv CLI path may fail with invalid generated `colorFrom`/`colorTo` metadata. Pushing to GitHub alone does not change the Hub Space unless that Space is configured to rebuild from that repo and branch; run the deploy script (with `HF_TOKEN`) after UI or API changes so the Docker image rebuilds. See `docker/space/README.md` for Dockerfile path, monorepo layout, and cache/reboot notes.
+`scripts/deploy_space_api.py` is the preferred deployment path for this repo because it uploads a valid Docker Space README frontmatter bundle through `huggingface_hub.HfApi`. `scripts/deploy_space.sh` remains available, but the current OpenEnv CLI path may fail with invalid generated `colorFrom`/`colorTo` metadata.
 
 Useful `scripts/deploy_space.sh` flags:
 

docs/evaluation.md

@@ -40,4 +40,6 @@ Final comparison must show positive or non-regressing behavior on:
 - timeout rate
 - failure visibility
 
-Current tracked smoke artifacts are not final evidence: `docs/results/improvement_report.json` currently records `improved: false`. Replace it after real SFT/GRPO training.
+Older smoke artifacts are retained for auditability, but final claims should use
+the curated bundle under `docs/results/final_submission_evidence/`. The root
+repository README is the canonical narrative and evidence map.

docs/final_submission_audit.md

@@ -1,42 +0,0 @@
-# Final Submission Audit
-
-Audit date: April 26, 2026.
-
-## Status Summary
-
-PolyGuard implements the participant-guide stack from dataset acquisition through OpenEnv environment, rewards, SFT, GRPO, inference, UI/API product, evaluation, and Hugging Face Space deployment. The public environment Space is live at `https://huggingface.co/spaces/TheJackBright/polyguard-openenv` and the runtime health endpoint returned `{"status":"healthy"}` during this audit.
-
-The only known judge-facing blocker is external storytelling: the README blog URL `https://huggingface.co/blog/TheJackBright/polyguard-openenv` currently returns 404 until `docs/hf_blog_draft.md` is published there or the README is updated with a real YouTube/slide/blog URL.
-
-## Requirement Matrix
-
-| Requirement area | Status | Evidence |
-| --- | --- | --- |
-| Problem statement and theme fit | Implemented | README describes safe long-horizon polypharmacy action selection under World Modeling / Professional Tasks. |
-| OpenEnv environment | Implemented | `openenv.yaml`, `PolyGuardEnv`, FastAPI `/reset`, `/step`, `/state`, `/metadata`, `/schema`, `/mcp`, and `/ws`; `uv run openenv validate .` passes. |
-| Dataset acquisition and preprocessing | Implemented | `scripts/bootstrap_data.py`, `scripts/ingest_open_drug_sources.py`, `scripts/build_training_corpus.py`, `data/processed/*`, `data/scenarios/*`, and `docs/dataset_report.md`. |
-| Easy/medium/hard curriculum | Implemented | Scenario JSON/JSONL sets plus task presets exposed through `/env/catalog`. |
-| Rewards and anti-hacking | Implemented | 13 reward components, 4 primary channels, bounded reward scaling, timeout handling, `app/env/anti_cheat.py`, and reward/anti-cheat tests. |
-| Training loop | Implemented | `scripts/train_sft_trl.py`, `scripts/train_grpo_trl.py`, `app/training/grpo_trl.py`, and `app/hf_space/training_runner.py`. |
-| TRL / Unsloth stack | Implemented with fallback reality documented | TRL path is active and reports `trl_transformers`; Unsloth is wired as optional but was unavailable in current reports. |
-| Post-training export and inference | Implemented | `scripts/merge_adapters_safe.py`, `scripts/test_inference_postsave.py`, active model manifest, and API/UI model status path. |
-| Product/demo | Implemented | FastAPI product API, React/Vite workbench, policy lab, training monitor, replay, dosing, and safety views. |
-| Results and plots | Implemented | Tracked `docs/results/*.json` and PNG plots, including SFT baseline sweep evidence and top-level environment-backed GRPO evidence. |
-| HF Space deployment | Implemented | Public Space is running on CPU basic, Space metadata is available, and tracked `docs/results/hf_space_verification.json` reports OpenEnv validation passed. |
-| Colab notebook | Implemented | README Colab URL targets `PolyGuard_SFT_GRPO_One_Run_Runner.ipynb`; `notebooks/09_training_loop.ipynb` is the modular alternative. |
-| Story artifact | Pending external publication | `docs/hf_blog_draft.md` exists, but the README blog URL returns 404 until published. |
-| Full public per-model GRPO sweep | Not claimed | Current public/tracked evidence is a 3-model SFT-baseline sweep plus a top-level GRPO run. Private training artifact repos require auth and must be mirrored before being used as public evidence. |
-
-## Fresh Verification
-
-- `uv run pytest`: 49 tests passed.
-- `uv run openenv validate .`: local OpenEnv validation passed.
-- `POLYGUARD_ENFORCE_SUBMISSION_LINKS=true uv run python scripts/acceptance_gate.py`: strict gate passed.
-- `curl -s https://thejackbright-polyguard-openenv.hf.space/health`: returned `{"status":"healthy"}`.
-- `curl -s https://thejackbright-polyguard-openenv.hf.space/metadata`: returned PolyGuard OpenEnv metadata with reward range `[0.001, 0.999]`.
-
-## Submission Notes
-
-- Publish the Hugging Face blog draft or replace the story URL before final hand-in.
-- Run `uv run python scripts/validate_submission_links.py` after publication to catch broken README URLs.
-- Do not add private HF artifact repos as judge-facing links unless they are made public or their outputs are mirrored into the repository/Space documentation.

docs/hf_blog_draft.md

@@ -1,17 +0,0 @@
-# PolyGuard OpenEnv Blog Draft
-
-PolyGuard turns polypharmacy safety into an OpenEnv-compatible reinforcement-learning environment. The agent sees a partially observable patient/regimen state, chooses constrained medication actions, and receives verifier-backed feedback over legality, safety, dosing quality, process fidelity, explanation grounding, uncertainty calibration, and anti-cheat checks.
-
-The environment targets the World Modeling / Professional Tasks theme. Medication optimization is not a one-shot answer task: safe action selection depends on state, evidence, comorbidities, labs, drug-drug interactions, uncertainty, and rollback behavior when an action is unsafe.
-
-The demo includes:
-
-- Easy, medium, and hard task presets over DDI screening, regimen risk, bandit mining, precision dosing, deprescribing, missing-data search, alternatives, and new-drug decomposition.
-- A React workbench for reset/step interaction, clickable candidates, task/environment selection, reward bars, action history, and event traces.
-- A TRL SFT warm start and GRPO loop using environment-backed rewards.
-- Post-save inference checks from exported artifacts.
-- Baseline comparison and plots committed under `docs/results/`.
-
-The current local compliance run uses a tiny model so the full pipeline can be verified quickly. For the final pitch, rerun the same notebook on GPU with the Qwen model and Unsloth enabled, then replace the result artifacts with the stronger run.
-
-Key result to show: the current benchmark report improves average reward over the no-change baseline while preserving legality. The reward design is intentionally decomposed into multiple independent checks to reduce reward hacking and make failures visible.

docs/mathematics.md

@@ -0,0 +1,1045 @@
+# Mathematics Behind PolyGuard Agents
+
+This note is the expert-facing mathematical map of PolyGuard: what the
+agents optimize, how actions are constrained, how reward is computed, and why
+the training stack uses SFT plus environment-verified GRPO instead of an
+unconstrained chat policy. It expands the shorter `docs/math.md`.
+
+Source-of-truth implementation files:
+
+- `app/env/env_core.py`: reset, observation, step, traces, OpenEnv state.
+- `app/models/policy/candidate_builder.py`: constrained candidate set.
+- `app/env/verifier.py`: hard legality and safety verifier.
+- `app/env/transition.py`: state transition dynamics.
+- `app/env/reward_router.py`: reward decomposition and aggregation.
+- `app/env/reward_scaling.py`: strict reward normalization.
+- `app/env/anti_cheat.py`: reward-hacking guards.
+- `app/agents/orchestrator.py`: multi-agent policy stack.
+- `app/models/baselines/contextual_bandit_policy.py`: LinUCB/Thompson co-policy.
+- `app/training/sft_trl.py`: supervised warm start.
+- `app/training/grpo_trl.py`: TRL GRPO with environment reward verification.
+
+## 1. Problem Formulation
+
+PolyGuard is best read as a finite-horizon constrained POMDP:
+
+```text
+M = (S, A, O, T, R, H, C)
+```
+
+where:
+
+- `S` is the latent patient/regimen state.
+- `A` is the set of medication actions expressible by `PolyGuardAction`.
+- `O` is the observation emitted to the agent.
+- `T(s' | s, a)` is the simulator transition.
+- `R(s, a, s')` is the verifier-backed reward.
+- `H` is the episode horizon, derived from sub-environment difficulty.
+- `C(s, a)` is the hard clinical/safety constraint predicate.
+
+The policy objective is:
+
+```text
+maximize_pi   E_pi [ sum_{t=0}^{H-1} R(s_t, a_t, s_{t+1}) ]
+subject to    C(s_t, a_t) = 1 whenever possible
+```
+
+There is no explicit discount factor in the runtime. Time preference enters
+through the finite horizon and the efficiency reward:
+
+```text
+efficiency_t = q(1 - step_count_t / (max_steps + 1))
+```
+
+where `q` is PolyGuard's reward clamp and quantizer:
+
+```text
+q(x) = round(clip(x, 0.001, 0.999), 3)
+```
+
+Why this framing: medication optimization is partially observable, long
+horizon, and safety constrained. A free-form language model objective would
+allow plausible but illegal actions. PolyGuard instead learns inside a small
+legal action set with explicit reward columns, so failures remain auditable.
+
+## 2. State, Observation, And Partial Observability
+
+The latent state `s_t` is represented by `PolyGuardState`:
+
+```text
+s_t = (
+  patient profile,
+  active decision mode,
+  step count,
+  max steps,
+  risk summary,
+  burden score,
+  precision dosing flags,
+  unresolved conflicts,
+  action history,
+  cumulative reward,
+  done flag
+)
+```
+
+At reset, the initial risk summary is:
+
+```text
+polypharmacy_count = number_of_medications
+burden_score       = min(1, number_of_medications / 12)
+severe_pair_count  = number_of_contraindicated_pairs
+```
+
+The agent does not receive all latent simulator internals. The observation
+`o_t = O(s_t)` exposes a controlled view:
+
+```text
+o_t = (
+  patient summary,
+  medication table,
+  comorbidities,
+  organ function and labs/vitals,
+  graph safety summary,
+  burden summary,
+  precision dosing flags,
+  unresolved conflicts,
+  candidate action set,
+  step budget,
+  action history,
+  warnings,
+  abstention indicators
+)
+```
+
+Uncertainty is a simple observable proxy:
+
+```text
+missing = I[egfr missing] + I[ast missing] + I[alt missing]
+base_uncertainty = missing / 3
+conflict_penalty = min(0.3, 0.1 * number_of_unresolved_conflicts)
+u_t = clip(base_uncertainty + conflict_penalty, 0, 1)
+```
+
+The environment recommends abstention/review when:
+
+```text
+u_t > 0.65
+```
+
+The supervisor uses a stricter routing threshold:
+
+```text
+mode_t = REVIEW    if u_t > 0.72
+mode_t = DOSE_OPT  if sub_environment = PRECISION_DOSING or dosing is active
+mode_t = REGIMEN_OPT otherwise
+```
+
+Why this choice: the observation keeps the agent honest. Missing labs and
+conflicts are not hidden from reward, but they are presented as uncertainty
+signals that should change policy behavior rather than invite overconfident
+recommendations.
+
+## 3. Constrained Action Model
+
+The runtime action is a strict `PolyGuardAction`:
+
+```text
+a_t = (
+  mode,
+  action_type,
+  target_drug,
+  replacement_drug,
+  dose_bucket,
+  taper_days,
+  monitoring_plan,
+  evidence_query,
+  new_drug_name,
+  candidate_components,
+  candidate_id,
+  confidence,
+  rationale_brief
+)
+```
+
+The environment first builds a candidate set:
+
+```text
+C_t = B(s_t)
+```
+
+where `B` is `build_candidates`. Candidate generation is rule-seeded and
+bounded:
+
+```text
+3 <= |C_t| <= 10
+```
+
+Each candidate carries proxy features:
+
+```text
+c = (
+  candidate_id,
+  mode,
+  action_type,
+  estimated_safety_delta,
+  burden_delta,
+  disease_stability_estimate,
+  uncertainty_score,
+  legality_precheck,
+  rationale_tags
+)
+```
+
+The legal candidate set is:
+
+```text
+L_t = { c in C_t : verifier(s_t, c).legal = true }
+```
+
+Policy selection is candidate selection, not arbitrary action synthesis:
+
+```text
+a_t = to_action(c_t),       c_t in C_t
+```
+
+The action type space is intentionally small:
+
+```text
+KEEP_REGIMEN
+STOP_DRUG
+SUBSTITUTE_WITHIN_CLASS
+RECOMMEND_ALTERNATIVE
+REDUCE_DOSE_BUCKET
+INCREASE_DOSE_BUCKET
+TAPER_INITIATE
+TAPER_CONTINUE
+DOSE_HOLD
+ORDER_MONITORING_AND_WAIT
+FETCH_EXTERNAL_EVIDENCE
+DECOMPOSE_NEW_DRUG
+REQUEST_SPECIALIST_REVIEW
+REQUEST_PHARMACIST_REVIEW
+```
+
+Why this choice: most safety failures in clinical LLM tasks come from an
+unbounded output space. PolyGuard makes the LLM solve ranking and explanation
+inside a constrained action manifold, then lets the verifier and transition
+system enforce semantics.
+
+## 4. Hard Legality Constraints
+
+The verifier computes:
+
+```text
+V(s_t, a_t) = (legal, violations, severity, fallback)
+```
+
+Examples of hard constraints:
+
+- The target drug must exist in the current regimen when required.
+- Substitutions and alternatives must be drawn from allowed substitution rules.
+- Evidence-fetch URLs must be allowlisted.
+- New-drug decomposition must include a new drug and components.
+- Abrupt stopping is illegal when taper rules require tapering.
+- Renal/hepatic unsafe dose escalation is illegal.
+- Duplicate therapy and contraindicated substitutions are illegal.
+- Monitoring/hold actions require a monitoring plan.
+- Destabilizing deprescribing patterns are illegal.
+
+The environment step uses a two-gate transition:
+
+```text
+if V(s_t, a_t).legal and not anti_cheat(s_t, a_t):
+    s_{t+1} = T(s_t, a_t)
+else:
+    s_{t+1} = rollback_state_with_failed_action_record(s_t, a_t)
+```
+
+Even blocked actions advance the step count and become visible in
+`action_history`, `failure_reasons`, `invalid_action_count`, and trace logs.
+
+Why this choice: legality is a constraint, not a soft preference. The reward
+still exposes illegal behavior numerically, but illegal behavior is prevented
+from mutating patient state.
+
+## 5. Transition Dynamics
+
+The transition function mutates the regimen and derived risk state. Important
+deterministic transitions include:
+
+```text
+STOP_DRUG:
+  medications' = medications without target_drug
+
+SUBSTITUTE_WITHIN_CLASS or RECOMMEND_ALTERNATIVE:
+  target_drug' = replacement_drug
+
+REDUCE_DOSE_BUCKET / INCREASE_DOSE_BUCKET:
+  dose_bucket moves one level over [LOW, MEDIUM, HIGH]
+
+DOSE_HOLD:
+  dose_bucket' = HOLD
+
+ORDER_MONITORING_AND_WAIT:
+  optional hold + unresolved review conflicts cleared
+
+REQUEST_*_REVIEW:
+  active_mode' = REVIEW
+  unresolved_conflicts append review marker
+
+FETCH_EXTERNAL_EVIDENCE:
+  external mention/component counts update
+  missing-data conflicts can be cleared
+
+DECOMPOSE_NEW_DRUG:
+  component count and unknown-risk flags update
+```
+
+After any applied transition, burden is recomputed with dose weights:
+
+```text
+w(LOW)    = 0.70
+w(MEDIUM) = 1.00
+w(HIGH)   = 1.25
+w(HOLD)   = 0.45
+w(NA)     = 1.00
+
+burden_{t+1} = clip( sum_{m in medications_{t+1}} w(dose_bucket_m) / 12, 0, 1 )
+```
+
+The severe-pair count is recomputed from known contraindicated pairs:
+
+```text
+severe_pair_count_{t+1} =
+  |{(i, j): i < j and contraindicated(drug_i, drug_j)}|
+```
+
+Why this choice: transitions are intentionally deterministic and inspectable.
+That makes reward debugging and training reproducibility easier than a hidden
+black-box clinical simulator.
+
+## 6. Multi-Agent Factorization
+
+PolyGuard's "agents" are a policy factorization, not independent RL learners
+with separate private rewards. Each module emits features, candidates, gates,
+or explanations consumed by the next stage:
+
+```text
+MedRec -> Evidence -> GraphSafety -> Dosing -> Candidate
+       -> Supervisor -> Planner -> Critic -> Env -> Explainer
+```
+
+The orchestrated policy can be written:
+
+```text
+pi(a | o) =
+  pi_critic(
+    pi_planner(
+      top_k_bandit(
+        pi_supervisor(
+          features_medrec,evidence,graph,dosing,candidates
+        )
+      )
+    )
+  )
+```
+
+More concretely:
+
+```text
+z_medrec  = f_medrec(s_t)
+z_evid    = f_evidence(s_t)
+z_graph   = f_graph(s_t)
+z_dose    = f_dosing(s_t)
+C_t       = f_candidate(s_t)
+m_t       = f_supervisor(s_t, z_dose)
+K_t       = f_bandit(C_t, m_t)
+a_hat_t   = f_planner(K_t, m_t, provider_prompt)
+a_t       = f_critic(s_t, a_hat_t)
+```
+
+Coordination modes change the graph behavior:
+
+- `sequential_pipeline`: one pass through the stack.
+- `supervisor_routed`: filters candidates by macro mode.
+- `replan_on_veto`: replans into review mode when the critic rejects.
+- `lightweight_debate`: allows a small debate/replan signal around vetoes.
+
+Why this choice: the decomposition creates audit points. Experts can inspect
+whether a failure came from candidate construction, uncertainty routing,
+planner choice, critic behavior, transition logic, or reward shaping.
+
+## 7. Graph Safety Mathematics
+
+The graph safety module summarizes regimen risk. In the no-artifact fallback,
+the encoder maps a regimen to a 24-dimensional vector:
+
+```text
+g = encode_regimen(drugs) in R^24
+```
+
+The vector includes hashed drug identity features, drug-class counts,
+side-effect tag load, medication count, contraindicated-pair count, and flags
+for sedative, anticoagulant, and glucose-lowering classes.
+
+Pairwise DDI severity is:
+
+```text
+score_pair(a, b) =
+  0.95 if contraindicated(a, b)
+  0.15 otherwise
+```
+
+Fallback severe-alert probability is:
+
+```text
+p_severe = min(0.99, 0.10 + 0.30 * number_of_risky_pairs)
+```
+
+Side-effect probabilities normalize ontology tag counts:
+
+```text
+p(tag) = count(tag across regimen) / sum_tag count(tag)
+```
+
+If a trained graph artifact exists, learned heads may override the fallback
+severe-alert and side-effect estimates.
+
+Why this choice: the graph model supplies dense safety features while the
+verifier still enforces hard contraindication rules. Learned risk can help
+ranking, but it is not trusted as the only safety barrier.
+
+## 8. Dosing Mathematics
+
+Dose-sensitive drugs are currently selected from sensitive classes:
+
+```text
+{anticoagulant, sedative, glucose_lowering}
+```
+
+Dose features include interaction load and organ stress:
+
+```text
+interaction_load = min(1, number_of_medications / 12)
+
+organ_stress = min(
+  1,
+  max(0, (35 - egfr) / 35)
+  + max(0, (ast - 80) / 80)
+  + max(0, (alt - 80) / 80)
+)
+```
+
+The surrogate PK/PD state is:
+
+```text
+x = (
+  effect_level,
+  toxicity_level,
+  underdose_risk,
+  organ_stress,
+  interaction_load
+)
+```
+
+Initial proxies:
+
+```text
+effect_0    = min(1, 0.35 + 0.45 * adherence)
+toxicity_0  = min(1, 0.08 + 0.40 * organ_stress)
+underdose_0 = max(0, 1 - effect_0)
+```
+
+For a dose change `d`:
+
+```text
+effective_delta = d * (1 - min(0.6, 0.4 * organ_stress))
+
+effect' =
+  clip(effect + 0.28 * effective_delta - 0.05 * interaction_load, 0, 1)
+
+toxicity_gain =
+  max(0, d) * (0.35 + 0.25 * organ_stress + 0.20 * interaction_load)
+
+toxicity' =
+  clip(0.85 * toxicity + toxicity_gain, 0, 1)
+
+underdose' =
+  clip(1 - effect' + 0.15 * max(0, -d), 0, 1)
+```
+
+Dosing quality proxies:
+
+```text
+target_attainment = clip(1 - |effect_level - 0.62|, 0, 1)
+toxicity_proxy    = min(1, toxicity + 0.20 * organ_stress + 0.12 * interaction_load)
+underdose_proxy   = min(1, underdose_risk + max(0, 0.30 - effect_level))
+measurement_need  = max(toxicity_proxy, underdose_proxy)
+```
+
+The runtime reward currently uses a coarse dose-mode reward:
+
+```text
+dosing_quality_score = 0.75 if action.mode = DOSE_OPT else 0.50
+```
+
+The detailed PK/PD analysis is still useful because it influences the agent
+stack and evaluation, even when the scalar reward channel remains deliberately
+simple.
+
+Why this choice: dose optimization needs its own state features, but dense
+dosing reward must not overpower legality and safety in early RL training.
+
+## 9. Contextual Bandit Co-Policy
+
+The bandit proposes a top-k shortlist before the planner finalizes an action.
+Each candidate becomes an 8-dimensional feature vector:
+
+```text
+x(c) = [
+  1,
+  I[legality_precheck],
+  estimated_safety_delta,
+  burden_delta,
+  disease_stability_estimate,
+  1 - uncertainty_score,
+  I[mode = DOSE_OPT],
+  I[mode = REVIEW]
+]
+```
+
+An arm is keyed by macro mode and action type:
+
+```text
+arm(c) = mode(c) || ":" || action_type(c)
+```
+
+### LinUCB
+
+For each arm `a`, PolyGuard maintains:
+
+```text
+A_a = I + sum x x^T
+b_a = sum r x
+theta_a = A_a^{-1} b_a
+```
+
+The score is:
+
+```text
+score_a(x) =
+  theta_a^T x + alpha * sqrt(x^T A_a^{-1} x)
+```
+
+where the default `alpha` is read from `POLYGUARD_BANDIT_ALPHA`, defaulting to
+`0.55`.
+
+### Thompson Sampling Variant
+
+The alternate score is:
+
+```text
+score_a(x) = theta_a^T x + Normal(0, alpha)
+```
+
+The absolute sampled noise is logged as the exploration bonus.
+
+### Explicit Exploration
+
+With probability `epsilon`, default `0.1`, the policy swaps the top candidate
+with another candidate in the sorted list:
+
+```text
+if Uniform(0, 1) < epsilon:
+    swap(scored[0], scored[random_non_top_index])
+```
+
+After the environment step:
+
+```text
+A_a <- A_a + x x^T
+b_a <- b_a + r x
+```
+
+Why this choice: the bandit gives a sample-efficient, inspectable exploration
+layer. It can improve candidate ordering without allowing the LLM to leave the
+safe candidate space.
+
+## 10. Planner Policy
+
+The planner receives candidates, a supervisor mode, and optional provider
+context. It filters candidates by mode when possible:
+
+```text
+C_t^m = { c in C_t : mode(c) = m_t }
+```
+
+Then the provider selects a candidate id:
+
+```text
+y_t ~ pi_theta(. | prompt(C_t^m, o_t))
+candidate_id = parse(y_t)
+a_hat_t = to_action(candidate_id)
+```
+
+If an active Transformers/adapter artifact is available, the model generates a
+completion and the runtime extracts a provided `cand_NN`. If no active artifact
+is available or loading fails, the deterministic safety ranker chooses:
+
+```text
+argmax_c (legality_precheck(c), estimated_safety_delta(c), -uncertainty_score(c))
+```
+
+The planner confidence is:
+
+```text
+confidence = max(0.45, 1 - uncertainty_score(candidate))
+```
+
+Why this choice: the learned policy is used where language models are useful:
+contextual judgment over a compact set plus rationale generation. Ranking
+fallbacks keep the product path deterministic and testable when model artifacts
+are unavailable.
+
+## 11. Critic And Safety Veto
+
+The critic re-runs the verifier:
+
+```text
+report = V(s_t, a_hat_t)
+```
+
+If the report is legal:
+
+```text
+a_t = a_hat_t
+```
+
+Otherwise, the critic returns a review-style fallback action. The environment
+still subjects that final action to the same legality and anti-cheat gates, so
+critic output is not privileged over the environment.
+
+Why this choice: the planner is allowed to be probabilistic, but state mutation
+is not. The critic provides an additional audit point before the environment
+transition.
+
+## 12. Anti-Cheat And Reward-Hacking Guards
+
+The anti-cheat detector computes an exploit predicate:
+
+```text
+E(s_t, a_t) in {0, 1}
+```
+
+It fires on:
+
+- repeated candidate loops over the last `MAX_REPEATED_ACTIONS = 3` actions;
+- excessive keep-regimen behavior after at least 3 actions;
+- excessive review behavior after at least 3 actions;
+- malformed candidate ids;
+- candidate ids outside the legal candidate set;
+- repeated no-op retries after failed actions;
+- parser exploit patterns in rationale text;
+- repeated no-op behavior on a hidden high-risk DDI holdout pair.
+
+The configured ratio thresholds are:
+
+```text
+MAX_KEEP_REGIMEN_RATIO = 0.6
+MAX_REVIEW_RATIO       = 0.5
+```
+
+Reward impact:
+
+```text
+anti_cheat_score = 0.001 if E(s_t, a_t) else 0.999
+```
+
+Termination impact:
+
+```text
+done = true, reason = "exploit_detection" if E(s_t, a_t)
+```
+
+Why this choice: RL policies exploit reward functions. PolyGuard makes common
+shortcuts explicit, penalized, and visible in traces instead of treating them
+as silent bad luck.
+
+## 13. Reward Components
+
+PolyGuard computes 13 reward columns. Every component is clamped by `q`.
+
+Let:
+
+```text
+u_t = overall uncertainty
+legal = V(s_t, a_t).legal
+exploit = E(s_t, a_t)
+pre_burden, post_burden = burden before/after step
+pre_pairs, post_pairs = severe-pair count before/after step
+```
+
+Risk-like deltas become rewards through:
+
+```text
+delta_reward(pre, post) = q(0.5 + 0.6 * (pre - post))
+```
+
+So:
+
+```text
+burden_reward = delta_reward(pre_burden, post_burden)
+pair_reward   = delta_reward(pre_pairs, post_pairs)
+
+safety_delta_score =
+  q(0.65 * pair_reward + 0.35 * burden_reward) if legal
+  0.001 otherwise
+```
+
+The current component formulas are:
+
+| Component | Formula |
+| --- | --- |
+| `format_compliance_score` | `0.999` after schema validation |
+| `candidate_alignment_score` | `0.999` if `candidate_id` starts with `cand_`, else `0.001` |
+| `legality_score` | `0.999` if legal, else `0.001` |
+| `safety_delta_score` | weighted pair/burden improvement if legal, else `0.001` |
+| `burden_improvement_score` | `burden_reward` if legal, else `0.001` |
+| `disease_stability_score` | `0.90` except `STOP_DRUG` or `INCREASE_DOSE_BUCKET`, which use `0.58` |
+| `dosing_quality_score` | `0.75` if action mode is `DOSE_OPT`, else `0.50` |
+| `abstention_quality_score` | `0.82` for review action with `u_t > 0.6`, else `0.56` |
+| `efficiency_score` | `q(1 - step_count / (max_steps + 1))` |
+| `process_fidelity_score` | `0.92` if legal, else `0.08` |
+| `explanation_grounding_score` | `0.80` if rationale exists, else `0.20` |
+| `anti_cheat_score` | `0.001` if exploit detected, else `0.999` |
+| `uncertainty_calibration_score` | `q(1 - |confidence - (1 - u_t)|)` |
+
+Sub-environment modifiers:
+
+```text
+WEB_SEARCH_MISSING_DATA:
+  FETCH_EXTERNAL_EVIDENCE:
+    process_fidelity_score >= 0.90
+    explanation_grounding_score >= 0.85
+  otherwise:
+    process_fidelity_score *= 0.75
+
+ALTERNATIVE_SUGGESTION:
+  RECOMMEND_ALTERNATIVE or SUBSTITUTE_WITHIN_CLASS:
+    safety_delta_score >= 0.88
+    burden_improvement_score >= 0.76
+  otherwise:
+    safety_delta_score *= 0.82
+
+NEW_DRUG_DECOMPOSITION:
+  DECOMPOSE_NEW_DRUG with components:
+    explanation_grounding_score >= 0.90
+    process_fidelity_score >= 0.88
+    uncertainty_calibration_score >= 0.82
+  otherwise:
+    explanation_grounding_score *= 0.70
+```
+
+Why this choice: dense reward reduces sparse-credit problems, but the columns
+are semantically separated so experts can detect when total reward improves
+for the wrong reason.
+
+## 14. Primary Reward Channels
+
+The 13 columns roll up into four primary channels:
+
+```text
+safety_legality =
+  avg(
+    legality_score,
+    candidate_alignment_score,
+    anti_cheat_score,
+    uncertainty_calibration_score
+  )
+
+clinical_improvement =
+  avg(
+    safety_delta_score,
+    burden_improvement_score,
+    disease_stability_score
+  )
+
+dosing_quality =
+  avg(
+    dosing_quality_score,
+    abstention_quality_score
+  )
+
+process_integrity =
+  avg(
+    format_compliance_score,
+    efficiency_score,
+    process_fidelity_score,
+    explanation_grounding_score
+  )
+```
+
+Each average is clamped through `q`. These channels are emitted in
+`info.primary_reward_channels`, GRPO logs, reports, plots, and ablation
+summaries.
+
+Why this choice: primary channels make the reward legible to judges and domain
+experts without hiding the lower-level reward columns needed for debugging.
+
+## 15. Total Reward
+
+The scalar environment reward is a weighted average:
+
+```text
+R_env(s_t, a_t, s_{t+1}) =
+  q( sum_i w_i c_i / sum_i w_i )
+```
+
+Current weights sum to 1:
+
+| Component | Weight |
+| --- | ---: |
+| `format_compliance_score` | `0.08` |
+| `candidate_alignment_score` | `0.08` |
+| `legality_score` | `0.12` |
+| `safety_delta_score` | `0.15` |
+| `burden_improvement_score` | `0.08` |
+| `disease_stability_score` | `0.10` |
+| `dosing_quality_score` | `0.08` |
+| `abstention_quality_score` | `0.06` |
+| `efficiency_score` | `0.06` |
+| `process_fidelity_score` | `0.06` |
+| `explanation_grounding_score` | `0.03` |
+| `anti_cheat_score` | `0.06` |
+| `uncertainty_calibration_score` | `0.04` |
+
+Safety-related terms have the largest combined mass:
+
+```text
+legality + safety_delta + burden + disease_stability + anti_cheat
+= 0.12 + 0.15 + 0.08 + 0.10 + 0.06
+= 0.51
+```
+
+That does not include candidate alignment or calibration, which also affect
+safety behavior.
+
+Why this choice: the scalar reward is needed by RL algorithms, but the weights
+make safety and clinical improvement dominate style, speed, and explanation.
+
+## 16. Episode Termination
+
+Termination is deterministic:
+
+```text
+done = true if:
+  exploit_detected
+  or step_count >= max_steps
+  or at least 3 recent invalid actions
+  or severe_pair_count >= 2 after enough steps
+  or burden_score > 0.92 after step 2
+  or burden_score < 0.25 and no unresolved conflicts
+  or wall-clock/step timeout
+```
+
+The main success-like terminal condition is:
+
+```text
+safe_resolution:
+  burden_score < 0.25 and unresolved_conflicts = empty
+```
+
+Why this choice: the environment needs both positive endings and explicit
+failure endings. Otherwise an RL policy could learn to loop, delay, or avoid
+difficult decisions.
+
+## 17. SFT Warm Start
+
+SFT trains the model to emit the target candidate id for curated examples. A
+record is serialized as:
+
+```text
+{
+  instruction: "Select the safest legal medication action candidate_id.",
+  medications: ...,
+  candidates: ...,
+  answer: target_candidate_id
+}
+```
+
+The mathematical objective is standard token-level negative log likelihood:
+
+```text
+L_SFT(theta) =
+  - sum_{(x, y*) in D} log pi_theta(y* | x)
+```
+
+where `y*` includes the target candidate id.
+
+Why this choice: SFT gives the policy the output format and obvious clinical
+priors before RL. Without SFT, GRPO would spend too much budget learning to
+name a valid candidate id.
+
+## 18. GRPO With Environment-Backed Reward
+
+GRPO prompts are built from patient/candidate records. For each prompt, the
+model emits one or more completions containing a candidate id:
+
+```text
+y_i ~ pi_theta(. | x),   i = 1..G
+```
+
+The environment verifier parses each completion, resets a deterministic
+PolyGuard environment using the recorded seed/difficulty/sub-environment, maps
+the candidate id to an action, takes one environment step, and returns a reward.
+
+The training reward used by the GRPO reward function is:
+
+```text
+legal_bonus = 0.95 if action is legal else 0.05
+
+R_GRPO =
+  q(0.80 * R_env + 0.20 * legal_bonus)
+```
+
+The reward function logs:
+
+```text
+generated_candidate_id
+selected_candidate_id
+legal
+reward
+reward_breakdown
+primary_reward_channels
+termination_reason
+```
+
+Conceptually, group-relative policy optimization forms a within-prompt
+advantage:
+
+```text
+A_i = (R_i - mean_j R_j) / (std_j R_j + epsilon)
+```
+
+and updates the policy with a clipped policy-ratio objective:
+
+```text
+rho_i(theta) = pi_theta(y_i | x) / pi_old(y_i | x)
+
+J_GRPO(theta) =
+  E[ (1/G) * sum_i min(
+        rho_i(theta) * A_i,
+        clip(rho_i(theta), 1 - eps, 1 + eps) * A_i
+      )
+      - beta * KL(pi_theta || pi_ref)
+    ]
+```
+
+The exact optimizer mechanics are owned by TRL's `GRPOTrainer`; PolyGuard's
+critical contribution is the reward function that executes verifier-backed
+environment transitions instead of scoring completions with a text-only judge.
+
+Why this choice: GRPO avoids training a separate value model, works naturally
+with multiple completions per prompt, and lets the environment supply rewards
+that are grounded in legality, transition effects, and anti-cheat checks.
+
+## 19. Evaluation Metrics
+
+Rollout metrics are sample means over environment steps or episodes:
+
+```text
+avg_reward      = mean_t R_t
+legality_rate   = mean_t I[action_t legal]
+success_rate    = mean_episode I[termination_reason = safe_resolution]
+abstention_rate = mean_t I[action_type starts with REQUEST_]
+timeout_rate    = timeout_count / number_of_rewards
+```
+
+Reward components and primary channels are averaged column-wise:
+
+```text
+avg_component_k = mean_t c_{t,k}
+avg_channel_j   = mean_t channel_{t,j}
+```
+
+Policy-stack ablations compare:
+
+```text
+bandit-only
+llm-only
+llm+bandit
+```
+
+Baselines include:
+
+```text
+no-change:
+  always KEEP_REGIMEN
+
+rules-only:
+  argmax_c (legality_precheck, estimated_safety_delta)
+
+greedy:
+  argmax_c (estimated_safety_delta, burden_delta)
+```
+
+Why this choice: average reward alone is not trustworthy. PolyGuard also
+reports legality, success, process fidelity, anti-cheat counts, invalid
+actions, timeouts, and failure visibility.
+
+## 20. What Experts Should Watch
+
+High-quality behavior should show:
+
+- High legality without collapsing into review-only actions.
+- Lower severe-pair and burden metrics over transitions.
+- Good uncertainty calibration: confidence near `1 - uncertainty`.
+- High process fidelity in special sub-environments.
+- Low exploit detection and low invalid-action counts.
+- GRPO reward improvements that are visible in primary channels, not just in
+  one easy component.
+
+Potential failure signatures:
+
+- Reward rises while `safety_legality` falls.
+- `abstention_quality_score` rises with review abuse.
+- Candidate alignment is high but `candidate_not_in_legal_set` appears in
+  anti-cheat logs.
+- Dosing mode is selected often without better target/toxicity metrics.
+- The policy exploits deterministic first-candidate fallbacks instead of
+  actually emitting candidate ids.
+
+The intended expert reading is therefore not "the scalar reward went up".
+The intended reading is:
+
+```text
+policy improved iff
+  scalar reward improves
+  and safety_legality does not regress
+  and clinical_improvement improves or stays justified
+  and process_integrity remains high
+  and anti-cheat/failure logs remain acceptable
+```
+
+## 21. Design Summary
+
+PolyGuard chooses:
+
+- A constrained POMDP/CMDP framing because free-form medication actions are
+  unsafe and hard to evaluate.
+- A hierarchical multi-agent policy because clinical medication decisions have
+  separable routing, candidate generation, critique, and explanation stages.
+- A contextual bandit shortlist because it is transparent, online-updateable,
+  and sample efficient.
+- SFT first because candidate-id format and clinical priors should not be
+  discovered from sparse RL reward.
+- GRPO next because group-relative rewards fit verifier-backed completion
+  scoring without a separate critic/value model.
+- Decomposed reward because safety-critical RL must be debuggable by reward
+  channel, not only by total return.
+- Hard verifier gates because some actions should be impossible to apply even
+  when a learned policy assigns them high probability.
+
+This is a research environment and simulator. The mathematics describes how
+PolyGuard trains and evaluates agents inside this controlled OpenEnv setting;
+it is not a clinical decision rule for patient care.

docs/participant_guide_traceability.md

@@ -27,7 +27,7 @@ This audit maps the hackathon guide, FAQ, and judging criteria to concrete PolyG
 - Current tracked reports include a non-fallback SFT run, a top-level non-fallback GRPO run, post-save inference, improvement reports, anti-hacking reports, and a 3-model SFT-baseline sweep.
 - The optional private remote artifact pull checks reward bounds, reward precision, missing charts, GRPO adapter paths, and the anti-hacking/overfit report. Do not describe private artifacts as public judge-facing links unless mirrored.
 - The strict submission gate passes as of April 26, 2026, but it validates link presence/shape, not live HTTP status.
-- The live public Space target is `TheJackBright/polyguard-openenv`; `/health` returned `{"status":"healthy"}` during this audit.
+- The live public Space target is `TheJackBright/polyguard-openenv-workbench`; `/health` is validated through the deployed workbench runtime.
 
 ## Remaining Human-Owned External Step
 

docs/results/README.md

@@ -1,24 +1,38 @@
 # Result Artifacts
 
-These tracked files mirror the latest local smoke/evaluation artifacts so the README can show stable evidence even though `outputs/` and `checkpoints/` are intentionally git-ignored.
+These tracked files mirror local smoke/evaluation artifacts and the final curated submission evidence even though `outputs/` and `checkpoints/` are intentionally git-ignored.
+
+The shared environment files, training scripts/notebooks, and training logs are
+indexed in `../submission_artifacts.md`.
 
 Current status:
 
 - OpenEnv structure/runtime validation passes locally.
 - Test suite passes locally.
 - Frontend production build passes locally.
-- SFT and GRPO artifacts in this folder are non-fallback TRL Transformers evidence from a tiny local compliance run.
-- `postsave_inference.json` loads the merged artifact rather than the fallback policy.
-- `improvement_report.json` shows positive average-reward improvement against the no-change baseline.
+- `final_submission_evidence/` is the current evidence bundle with curated charts, action traces, final reports, and the public HF artifact Space manifest.
+- `final_submission_evidence/charts/curated/` is the visually reviewed, non-redundant viewing layer used by the root README.
+- `final_submission_evidence/charts/all/` keeps the full chart pool.
+- `final_submission_evidence/charts/stale_superseded/` documents older 0.5B/1.5B-only charts and smoke-run mirrors that are retained for auditability.
+- Final artifact Space: https://huggingface.co/spaces/adithya9903/polyguard-openenv-final-artifacts
+- Qwen 3B SFT/GRPO adapter files and checkpoint tree are available through the final artifact Space; Qwen 0.5B and 1.5B currently have reports/history/post-save SFT evidence but no adapter directories in the checked mirrors.
+- `postsave_inference.json` loads the merged artifact rather than the fallback policy for the older smoke path.
+- `improvement_report.json` shows positive average-reward improvement against the no-change baseline for the older smoke path.
 - `hf_space_verification.json` records a live Hugging Face Space validation pass.
-- `active_model_manifest.json` records the currently activated local product model. As of April 26, 2026 this points at the local Qwen 0.5B smoke artifact while the full remote Qwen sweep continues.
 
-For a stronger final pitch, replace these artifacts after a larger Colab/HF GPU run:
+Best current evidence:
+
+- `final_submission_evidence/charts/curated/training/sft_loss_curves_all_models.png`
+- `final_submission_evidence/charts/curated/training/qwen_3b_grpo_reward_curve.png`
+- `final_submission_evidence/charts/curated/training/qwen_3b_grpo_loss_curve.png`
+- `final_submission_evidence/charts/curated/model_comparison/sft_vs_grpo_reward_by_model.png`
+- `final_submission_evidence/charts/curated/model_comparison/qwen_model_grpo_reward.png`
+- `final_submission_evidence/charts/curated/product_over_basic_llm/basic_llm_vs_full_pipeline_reward.png`
+- `final_submission_evidence/charts/curated/product_over_basic_llm/reward_delta_by_seed.png`
+- `final_submission_evidence/charts/curated/reward_and_safety/reward_component_bars.png`
+- `final_submission_evidence/charts/curated/inference/inference_validity_reward.png`
+- `final_submission_evidence/reports/basic_llm_vs_polyguard_report.json`
+- `final_submission_evidence/reports/action_traces.jsonl`
+- `final_submission_evidence/manifest.json`
 
-- `sft_trl_run.json`
-- `grpo_trl_run.json`
-- `postsave_inference.json`
-- `improvement_report.json`
-- all plot PNGs
-- `hf_space_verification.json`
-- `active_model_manifest.json`
+Older smoke artifacts remain here for auditability and regression checks. The root compatibility charts such as `avg_reward.png` and `policy_stack_avg_reward.png` are intentionally left in place because local gates still check them.

docs/results/final_submission_evidence/README.md

@@ -0,0 +1,77 @@
+# PolyGuard Final Submission Evidence
+
+This folder is the current curated evidence set for the final submission. It
+replaces the earlier Qwen 0.5B/1.5B-only view with a single location for the
+best charts, reports, action traces, and model-artifact availability.
+
+## Hugging Face Artifact Space
+
+- Space: [adithya9903/polyguard-openenv-final-artifacts](https://huggingface.co/spaces/adithya9903/polyguard-openenv-final-artifacts)
+- The root repository README is the primary public narrative. This folder is the
+  supporting local mirror for charts, reports, traces, and artifact availability.
+
+## Shared Environment, Logs, And Scripts
+
+The full index for shared environment files, training scripts, notebooks, and
+training logs is [Submission Artifact Index](../../submission_artifacts.md).
+
+- Environment/runtime: `openenv.yaml`, `pyproject.toml`, `uv.lock`, `requirements*.txt`, `Dockerfile*`, `app/env/`, `server/app.py`, and `app/hf_space/Dockerfile`.
+- Training scripts/notebooks: `PolyGuard_SFT_GRPO_One_Run_Runner.ipynb`, `notebooks/09_training_loop.ipynb`, `scripts/train_sft_trl.py`, `scripts/train_grpo_trl.py`, `scripts/deploy_training_space.py`, and `app/hf_space/training_runner.py`.
+- Training logs/results: this folder's `reports/`, `docs/results/sweeps/`, and `docs/results/submission_evidence_qwen_0_5b_1_5b_3b/reports/`.
+
+## Artifact Availability
+
+| Model | SFT adapter | GRPO adapter | Checkpoints | Reports | Status |
+| --- | --- | --- | --- | --- | --- |
+| Qwen 0.5B | missing | missing | missing | yes | reports_only_or_partial |
+| Qwen 1.5B | missing | missing | missing | yes | reports_only_or_partial |
+| Qwen 3B | yes | yes | yes | yes | complete |
+
+Qwen 0.5B and 1.5B currently have SFT histories/reports and post-save SFT
+evidence in this repository, but no downloadable SFT/GRPO adapter directories
+were present in the local checkout or authenticated artifact repos at packaging
+time. Qwen 3B has both SFT and GRPO adapters, checkpoint metadata/intermediate
+checkpoints, GRPO history, post-save GRPO inference, and policy ablation
+evidence.
+
+## Chart Organization
+
+- `charts/curated/` is the visually reviewed, non-redundant submission view.
+- `charts/all/` is the full chart pool, including individual run curves and diagnostics.
+- `charts/frontpage/` is kept as the earlier compact compatibility set.
+- `charts/stale_superseded/` documents older 0.5B/1.5B-only charts and smoke-run mirrors.
+
+Recommended README charts:
+
+- `charts/curated/training/sft_loss_curves_all_models.png`
+- `charts/curated/training/qwen_3b_grpo_reward_curve.png`
+- `charts/curated/training/qwen_3b_grpo_loss_curve.png`
+- `charts/curated/model_comparison/sft_vs_grpo_reward_by_model.png`
+- `charts/curated/model_comparison/qwen_model_grpo_reward.png`
+- `charts/curated/product_over_basic_llm/basic_llm_vs_full_pipeline_reward.png`
+- `charts/curated/product_over_basic_llm/reward_delta_by_seed.png`
+- `charts/curated/reward_and_safety/reward_component_bars.png`
+- `charts/curated/inference/inference_validity_reward.png`
+
+## Improvement Evidence
+
+- Basic LLM proxy vs full PolyGuard pipeline reward delta:
+  `0.043` average reward.
+- Full pipeline legality rate: `1.0`.
+- Basic LLM failure/exploit rate: `0.25`.
+- Full pipeline failure/exploit rate: `0.0`.
+
+Reward values in the tracked API/reports remain numeric and clamped to
+`[0.001, 0.999]` at three decimal precision.
+
+## Visual Review Notes
+
+The README uses the clearest training, comparison, and product-lift charts. A
+few diagnostics are intentionally kept out of the top-level README: the
+train-vs-holdout gap plot is effectively zero-gap/blank, the anti-cheat chart
+is audit-oriented, and policy-ablation reward is supplemental because the
+product-over-basic-LLM charts communicate the improvement more directly.
+
+See `charts/curated/README.md` for the full curated index and
+`charts/stale_superseded/README.md` for superseded 0.5B/1.5B-only charts and
+smoke mirrors.