Deploy PolyGuard: nginx + OpenEnv + API + static UI (CPU)

.dockerignore

@@ -0,0 +1,21 @@
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.git
+.gitignore
+*.md
+!README.md
+node_modules
+app/ui/frontend/node_modules
+app/ui/frontend/dist
+checkpoints/active
+checkpoints/.hf_bundles
+outputs
+.env
+*.log
+submission_bundle
+notebooks
+.pytest_cache

.env.example

@@ -0,0 +1,22 @@
+POLYGUARD_DATA_DIR=./data
+POLYGUARD_LOG_LEVEL=INFO
+POLYGUARD_SEED=42
+POLYGUARD_ENV_HOST=127.0.0.1
+POLYGUARD_ENV_PORT=8100
+POLYGUARD_API_HOST=127.0.0.1
+POLYGUARD_API_PORT=8200
+POLYGUARD_UI_PORT=5173
+POLYGUARD_ENABLE_OLLAMA=false
+POLYGUARD_OLLAMA_MODEL=qwen2.5:3b-instruct
+# Optional explicit order (comma-separated): transformers,ollama
+# POLYGUARD_PROVIDER_PREFERENCE=transformers,ollama
+POLYGUARD_PROVIDER_TIMEOUT_SECONDS=25
+# Trained checkpoint (GRPO adapter + merged + SFT) from HF: run
+#   python scripts/install_hf_active_bundle.py
+# Then enable loading from checkpoints/active/active_model_manifest.json.
+POLYGUARD_ENABLE_ACTIVE_MODEL=true
+POLYGUARD_HF_MODEL=Qwen/Qwen2.5-0.5B-Instruct
+POLYGUARD_FRONTIER_MODEL=Qwen/Qwen2.5-7B-Instruct
+POLYGUARD_ALLOW_WEB_FETCH=false
+POLYGUARD_REWARD_MIN=0.001
+POLYGUARD_REWARD_MAX=0.999

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+app/ui/frontend/dist/blackhole.webm filter=lfs diff=lfs merge=lfs -text
+app/ui/frontend/public/blackhole.webm filter=lfs diff=lfs merge=lfs -text
+docs/results/model_improvement_evidence_qwen_0_5b_1_5b/charts/reward_function/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
+docs/results/qwen_completed_runs/charts/generated/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
+docs/results/submission_evidence/qwen_0_5b_1_5b/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
+docs/results/submission_evidence/qwen_0_5b_1_5b_3b/reward_component_bars.png filter=lfs diff=lfs merge=lfs -text
+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

.gitignore

@@ -0,0 +1,29 @@
+.DS_Store
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+.env
+node_modules/
+dist/
+build/
+*.log
+# Weight bundles and run outputs are local-only; tracked READMEs explain layout.
+checkpoints/*
+!checkpoints/README.md
+outputs/*
+!outputs/README.md
+artifacts/
+submission_bundle/model_artifacts/
+submission_bundle/*.zip
+data/cache/*
+data/processed/*
+data/synthetic/*
+data/retrieval_index/*
+!data/**/.gitkeep
+app/ui/frontend/.vite/
+/demo.md

Dockerfile

@@ -0,0 +1,41 @@
+# 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
+COPY app/ui/frontend/package.json app/ui/frontend/package-lock.json ./
+RUN npm ci
+COPY app/ui/frontend/ ./
+ENV VITE_API_BASE=/api
+RUN npm run build
+
+FROM python:3.11-slim-bookworm
+WORKDIR /app
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends nginx \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements-space.txt /app/requirements-space.txt
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir -r /app/requirements-space.txt
+
+COPY . /app
+COPY --from=frontend /build/dist /app/static
+
+RUN chmod +x /app/docker/space/entrypoint.sh \
+    && mkdir -p /app/data /app/checkpoints/active
+
+ENV PORT=7860
+ENV POLYGUARD_ALLOW_HF_SPACE_CORS=true
+ENV POLYGUARD_ENABLE_OLLAMA=false
+ENV POLYGUARD_ENABLE_ACTIVE_MODEL=true
+ENV POLYGUARD_HF_MODEL=Qwen/Qwen2.5-0.5B-Instruct
+ENV POLYGUARD_PROVIDER_PREFERENCE=transformers
+ENV POLYGUARD_ALLOW_WEB_FETCH=false
+ENV POLYGUARD_DATA_DIR=/app/data
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+CMD ["/app/docker/space/entrypoint.sh"]

Dockerfile.space

@@ -0,0 +1,41 @@
+# 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
+COPY app/ui/frontend/package.json app/ui/frontend/package-lock.json ./
+RUN npm ci
+COPY app/ui/frontend/ ./
+ENV VITE_API_BASE=/api
+RUN npm run build
+
+FROM python:3.11-slim-bookworm
+WORKDIR /app
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends nginx \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements-space.txt /app/requirements-space.txt
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir -r /app/requirements-space.txt
+
+COPY . /app
+COPY --from=frontend /build/dist /app/static
+
+RUN chmod +x /app/docker/space/entrypoint.sh \
+    && mkdir -p /app/data /app/checkpoints/active
+
+ENV PORT=7860
+ENV POLYGUARD_ALLOW_HF_SPACE_CORS=true
+ENV POLYGUARD_ENABLE_OLLAMA=false
+ENV POLYGUARD_ENABLE_ACTIVE_MODEL=true
+ENV POLYGUARD_HF_MODEL=Qwen/Qwen2.5-0.5B-Instruct
+ENV POLYGUARD_PROVIDER_PREFERENCE=transformers
+ENV POLYGUARD_ALLOW_WEB_FETCH=false
+ENV POLYGUARD_DATA_DIR=/app/data
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+CMD ["/app/docker/space/entrypoint.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,29 @@
+.PHONY: install test lint env api ui smoke run-all
+
+VENV_DIR := .venv
+PYTHON := $(VENV_DIR)/bin/python
+PIP := $(VENV_DIR)/bin/pip
+
+$(PYTHON):
+	python3 -m venv $(VENV_DIR)
+
+install: $(PYTHON)
+	bash scripts/bootstrap_venv.sh
+
+test: $(PYTHON)
+	PYTHONPATH=. $(PYTHON) -m pytest
+
+env: $(PYTHON)
+	PYTHONPATH=. $(PYTHON) -m app.env.fastapi_app
+
+api: $(PYTHON)
+	PYTHONPATH=. $(PYTHON) -m app.api
+
+ui:
+	cd app/ui/frontend && npm install && npm run dev
+
+smoke:
+	bash scripts/smoke_test_all.sh
+
+run-all: $(PYTHON)
+	bash scripts/run_all_local.sh --full

PolyGuard_SFT_GRPO_One_Run_Runner.ipynb

@@ -0,0 +1,481 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# PolyGuard SFT + GRPO One-Run Runner\n",
+        "\n",
+        "`POLYGUARD_ONE_RUN_RUNNER`\n",
+        "\n",
+        "Run this notebook from top to bottom to execute the PolyGuard pipeline from data build through SFT baseline training, GRPO environment-reward training, artifact pull, inference validation, report/chart generation, and Hugging Face Space deployment.\n",
+        "\n",
+        "Default behavior uses Hugging Face Spaces for GPU training, not local Ollama or local GPU training. Keep `HF_TOKEN` in an environment variable or notebook secret; do not paste it into a cell output or commit it.\n",
+        "\n",
+        "Reward values are expected to remain numeric, rounded to 3 decimals, and clamped to `[0.001, 0.999]` throughout the API, reports, and charts."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 0) Configuration Notes\n",
+        "\n",
+        "The notebook is intentionally root-level in `polyguard-rl/`. If opened from Colab without the rest of the repo, the first cell clones the GitHub repo and changes into `polyguard-rl/`.\n",
+        "\n",
+        "Useful overrides:\n",
+        "\n",
+        "- `HF_TOKEN`: write token for Spaces, model artifact repos, and private artifact pulls.\n",
+        "- `HF_USERNAME`: target Hub namespace. If omitted, the authenticated username is used.\n",
+        "- `POLYGUARD_MODEL_SWEEP`: comma-separated models, default Qwen 0.5B, 1.5B, and 3B instruct.\n",
+        "- `POLYGUARD_SFT_EPOCHS`, `POLYGUARD_GRPO_EPOCHS`: training epochs.\n",
+        "- `POLYGUARD_SFT_MAX_STEPS=0`, `POLYGUARD_GRPO_MAX_STEPS=0`, `POLYGUARD_GRPO_MAX_PROMPTS=0`: full-corpus/full-epoch mode.\n",
+        "- `POLYGUARD_WAIT_FOR_REMOTE_TRAINING=1`: keep polling until artifacts are pulled or timeout hits.\n",
+        "- `POLYGUARD_RUN_LOCAL_SMOKE=1`: also run a tiny local SFT/GRPO smoke loop."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from __future__ import annotations\n",
+        "\n",
+        "import json\n",
+        "import os\n",
+        "from pathlib import Path\n",
+        "import subprocess\n",
+        "import sys\n",
+        "import time\n",
+        "\n",
+        "PROJECT_SUBDIR = \"polyguard-rl\"\n",
+        "DEFAULT_REPO_URL = \"https://github.com/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK.git\"\n",
+        "REPO_URL = os.getenv(\"POLYGUARD_GITHUB_REPO_URL\", DEFAULT_REPO_URL)\n",
+        "\n",
+        "cwd = Path.cwd().resolve()\n",
+        "if (cwd / \"pyproject.toml\").exists() and (cwd / \"scripts\").exists():\n",
+        "    ROOT = cwd\n",
+        "elif (cwd / PROJECT_SUBDIR / \"pyproject.toml\").exists():\n",
+        "    ROOT = cwd / PROJECT_SUBDIR\n",
+        "else:\n",
+        "    clone_root = Path(os.getenv(\"POLYGUARD_REPO_DIR\", \"/content/Meta_Pytorch_OpenEnv_Scaler_VK\")).resolve()\n",
+        "    if not clone_root.exists():\n",
+        "        subprocess.run([\"git\", \"clone\", REPO_URL, str(clone_root)], check=True)\n",
+        "    ROOT = clone_root / PROJECT_SUBDIR\n",
+        "\n",
+        "os.chdir(ROOT)\n",
+        "print(f\"PolyGuard root: {ROOT}\")\n",
+        "\n",
+        "def run(cmd: list[str] | str, *, check: bool = True, env: dict[str, str] | None = None) -> subprocess.CompletedProcess[str]:\n",
+        "    printable = cmd if isinstance(cmd, str) else \" \".join(cmd)\n",
+        "    print(f\"\\n$ {printable}\")\n",
+        "    merged_env = os.environ.copy()\n",
+        "    if env:\n",
+        "        merged_env.update(env)\n",
+        "    completed = subprocess.run(cmd, check=False, text=True, env=merged_env)\n",
+        "    if check and completed.returncode != 0:\n",
+        "        raise RuntimeError(f\"command_failed:{printable}\")\n",
+        "    return completed\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Install local runtime dependencies. This keeps the notebook kernel light while project commands run through uv.\n",
+        "run([sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"-U\", \"uv\", \"huggingface_hub\", \"gradio_client\"])\n",
+        "run([\"uv\", \"sync\"])\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "def read_colab_secret(name: str) -> str:\n",
+        "    try:\n",
+        "        from google.colab import userdata  # type: ignore\n",
+        "    except Exception:\n",
+        "        return \"\"\n",
+        "    try:\n",
+        "        return str(userdata.get(name) or \"\")\n",
+        "    except Exception:\n",
+        "        return \"\"\n",
+        "\n",
+        "HF_TOKEN = os.getenv(\"HF_TOKEN\", \"\") or read_colab_secret(\"HF_TOKEN\")\n",
+        "if HF_TOKEN:\n",
+        "    os.environ[\"HF_TOKEN\"] = HF_TOKEN\n",
+        "\n",
+        "if os.getenv(\"POLYGUARD_REQUIRE_HF_TOKEN\", \"1\") == \"1\" and not HF_TOKEN:\n",
+        "    raise RuntimeError(\"Set HF_TOKEN as an environment variable or Colab secret before running the remote training cells.\")\n",
+        "\n",
+        "HF_USERNAME = os.getenv(\"HF_USERNAME\", \"\")\n",
+        "if HF_TOKEN and not HF_USERNAME:\n",
+        "    from huggingface_hub import HfApi\n",
+        "\n",
+        "    whoami = HfApi(token=HF_TOKEN).whoami(token=HF_TOKEN)\n",
+        "    HF_USERNAME = str(whoami.get(\"name\") or whoami.get(\"fullname\") or \"\")\n",
+        "\n",
+        "if not HF_USERNAME:\n",
+        "    HF_USERNAME = \"TheJackBright\"\n",
+        "\n",
+        "MODEL_SWEEP = os.getenv(\n",
+        "    \"POLYGUARD_MODEL_SWEEP\",\n",
+        "    \"Qwen/Qwen2.5-0.5B-Instruct,Qwen/Qwen2.5-1.5B-Instruct,Qwen/Qwen2.5-3B-Instruct\",\n",
+        ")\n",
+        "TRAINING_SPACE_REPO_ID = os.getenv(\"POLYGUARD_TRAINING_SPACE_REPO_ID\", f\"{HF_USERNAME}/polyguard-openenv-training-full\")\n",
+        "ARTIFACT_REPO_ID = os.getenv(\"POLYGUARD_ARTIFACT_REPO_ID\", f\"{HF_USERNAME}/polyguard-openenv-training-full-artifacts\")\n",
+        "PRODUCT_SPACE_REPO_ID = os.getenv(\"POLYGUARD_PRODUCT_SPACE_REPO_ID\", f\"{HF_USERNAME}/polyguard-openenv\")\n",
+        "\n",
+        "SFT_EPOCHS = os.getenv(\"POLYGUARD_SFT_EPOCHS\", \"2\")\n",
+        "GRPO_EPOCHS = os.getenv(\"POLYGUARD_GRPO_EPOCHS\", \"1\")\n",
+        "SFT_MAX_STEPS = os.getenv(\"POLYGUARD_SFT_MAX_STEPS\", \"0\")\n",
+        "GRPO_MAX_STEPS = os.getenv(\"POLYGUARD_GRPO_MAX_STEPS\", \"0\")\n",
+        "GRPO_MAX_PROMPTS = os.getenv(\"POLYGUARD_GRPO_MAX_PROMPTS\", \"0\")\n",
+        "GRPO_NUM_GENERATIONS = os.getenv(\"POLYGUARD_GRPO_NUM_GENERATIONS\", \"2\")\n",
+        "DATA_PROFILE = os.getenv(\"POLYGUARD_DATA_PROFILE\", \"massive\")\n",
+        "\n",
+        "RUN_REMOTE_TRAINING = os.getenv(\"POLYGUARD_RUN_REMOTE_TRAINING\", \"1\") == \"1\"\n",
+        "WAIT_FOR_REMOTE_TRAINING = os.getenv(\"POLYGUARD_WAIT_FOR_REMOTE_TRAINING\", \"1\") == \"1\"\n",
+        "RUN_LOCAL_SMOKE = os.getenv(\"POLYGUARD_RUN_LOCAL_SMOKE\", \"0\") == \"1\"\n",
+        "DEPLOY_PRODUCT_SPACE = os.getenv(\"POLYGUARD_DEPLOY_PRODUCT_SPACE\", \"1\") == \"1\"\n",
+        "PRODUCT_SPACE_PRIVATE = os.getenv(\"POLYGUARD_PRODUCT_SPACE_PRIVATE\", \"0\") == \"1\"\n",
+        "REMOTE_TIMEOUT_HOURS = float(os.getenv(\"POLYGUARD_REMOTE_TIMEOUT_HOURS\", \"12\"))\n",
+        "REMOTE_POLL_SECONDS = int(os.getenv(\"POLYGUARD_REMOTE_POLL_SECONDS\", \"300\"))\n",
+        "\n",
+        "print(json.dumps({\n",
+        "    \"hf_username\": HF_USERNAME,\n",
+        "    \"model_sweep\": MODEL_SWEEP,\n",
+        "    \"training_space_repo_id\": TRAINING_SPACE_REPO_ID,\n",
+        "    \"artifact_repo_id\": ARTIFACT_REPO_ID,\n",
+        "    \"product_space_repo_id\": PRODUCT_SPACE_REPO_ID,\n",
+        "    \"data_profile\": DATA_PROFILE,\n",
+        "    \"run_remote_training\": RUN_REMOTE_TRAINING,\n",
+        "    \"wait_for_remote_training\": WAIT_FOR_REMOTE_TRAINING,\n",
+        "    \"run_local_smoke\": RUN_LOCAL_SMOKE,\n",
+        "    \"deploy_product_space\": DEPLOY_PRODUCT_SPACE,\n",
+        "}, indent=2))\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 1) Build Data And Training Corpora\n",
+        "\n",
+        "This builds processed data, scenario artifacts, SFT records, and GRPO prompt episodes. The training Space repeats the full build inside its container so remote training is reproducible."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "run([\"uv\", \"run\", \"python\", \"scripts/bootstrap_data.py\"])\n",
+        "run([\n",
+        "    \"uv\", \"run\", \"python\", \"scripts/build_training_corpus.py\",\n",
+        "    \"--profile\", DATA_PROFILE,\n",
+        "    \"--with-local\",\n",
+        "    \"--with-synthetic\",\n",
+        "    \"--with-hf\",\n",
+        "])\n",
+        "summary_path = Path(\"data/processed/training_corpus_summary.json\")\n",
+        "print(summary_path.read_text(encoding=\"utf-8\") if summary_path.exists() else \"training_corpus_summary_missing\")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 2) Local Contract Checks\n",
+        "\n",
+        "These checks verify the package, OpenEnv contract, reward bounds, and report-generation surfaces before spending GPU time."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "run([\"uv\", \"run\", \"pytest\"])\n",
+        "run([\"uv\", \"run\", \"openenv\", \"validate\", \".\"])\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 3) Optional Local Smoke SFT And GRPO\n",
+        "\n",
+        "The final training path is the HF Space below. Set `POLYGUARD_RUN_LOCAL_SMOKE=1` only if you want a tiny local compliance run before the remote job."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "if RUN_LOCAL_SMOKE:\n",
+        "    local_model = os.getenv(\"POLYGUARD_LOCAL_SMOKE_MODEL\", \"Qwen/Qwen2.5-0.5B-Instruct\")\n",
+        "    run([\n",
+        "        \"uv\", \"run\", \"python\", \"scripts/train_sft_trl.py\",\n",
+        "        \"--model-id\", local_model,\n",
+        "        \"--dataset-path\", \"data/processed/training_corpus_sft.json\",\n",
+        "        \"--output-dir\", \"checkpoints/sft_adapter\",\n",
+        "        \"--report-path\", \"outputs/reports/sft_trl_run.json\",\n",
+        "        \"--epochs\", \"1\",\n",
+        "        \"--max-steps\", \"20\",\n",
+        "        \"--batch-size\", \"1\",\n",
+        "        \"--use-unsloth\",\n",
+        "    ])\n",
+        "    run([\n",
+        "        \"uv\", \"run\", \"python\", \"scripts/train_grpo_trl.py\",\n",
+        "        \"--model-id\", local_model,\n",
+        "        \"--prompts-path\", \"data/processed/training_corpus_grpo_prompts.jsonl\",\n",
+        "        \"--output-dir\", \"checkpoints/grpo_adapter\",\n",
+        "        \"--report-path\", \"outputs/reports/grpo_trl_run.json\",\n",
+        "        \"--max-steps\", \"20\",\n",
+        "        \"--max-prompts\", \"64\",\n",
+        "        \"--num-generations\", \"2\",\n",
+        "        \"--batch-size\", \"1\",\n",
+        "        \"--use-unsloth\",\n",
+        "    ])\n",
+        "else:\n",
+        "    print(\"Local smoke skipped. Remote HF Space training remains the main path.\")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 4) Start SFT Baseline And GRPO Training On Hugging Face Spaces\n",
+        "\n",
+        "This deploys the private training Space and artifact repo, starts the Docker runner, builds the full corpus inside the Space, trains SFT as the baseline, trains GRPO with environment-backed rewards, runs post-save inference and ablations, then uploads reports, plots, adapters, and manifests."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "if RUN_REMOTE_TRAINING:\n",
+        "    deploy_cmd = [\n",
+        "        \"uv\", \"run\", \"python\", \"scripts/deploy_training_space.py\",\n",
+        "        \"--repo-id\", TRAINING_SPACE_REPO_ID,\n",
+        "        \"--artifact-repo-id\", ARTIFACT_REPO_ID,\n",
+        "        \"--hardware\", os.getenv(\"POLYGUARD_HF_HARDWARE\", \"a10g-large\"),\n",
+        "        \"--model-sweep\", MODEL_SWEEP,\n",
+        "        \"--training-mode\", os.getenv(\"POLYGUARD_TRAINING_MODE\", \"full\"),\n",
+        "        \"--sft-epochs\", SFT_EPOCHS,\n",
+        "        \"--grpo-epochs\", GRPO_EPOCHS,\n",
+        "        \"--sft-max-steps\", SFT_MAX_STEPS,\n",
+        "        \"--grpo-max-steps\", GRPO_MAX_STEPS,\n",
+        "        \"--grpo-max-prompts\", GRPO_MAX_PROMPTS,\n",
+        "        \"--grpo-num-generations\", GRPO_NUM_GENERATIONS,\n",
+        "    ]\n",
+        "    if os.getenv(\"POLYGUARD_TRAINING_SPACE_PUBLIC\", \"0\") == \"1\":\n",
+        "        deploy_cmd.append(\"--public\")\n",
+        "    run(deploy_cmd)\n",
+        "    print(f\"Training Space: https://huggingface.co/spaces/{TRAINING_SPACE_REPO_ID}\")\n",
+        "    print(f\"Artifact repo: https://huggingface.co/{ARTIFACT_REPO_ID}\")\n",
+        "else:\n",
+        "    print(\"Remote training deployment skipped by POLYGUARD_RUN_REMOTE_TRAINING=0\")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 5) Monitor Space And Pull Artifacts\n",
+        "\n",
+        "If `POLYGUARD_WAIT_FOR_REMOTE_TRAINING=1`, this cell keeps polling until `scripts/pull_training_artifacts.py` succeeds or the timeout is reached. It never prints the token."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "monitor_output = \"outputs/reports/training_space_runtime_status.json\"\n",
+        "\n",
+        "def monitor_once() -> int:\n",
+        "    return run([\n",
+        "        \"uv\", \"run\", \"python\", \"scripts/monitor_training_space_status.py\",\n",
+        "        \"--space-id\", TRAINING_SPACE_REPO_ID,\n",
+        "        \"--artifact-repo-id\", ARTIFACT_REPO_ID,\n",
+        "        \"--output\", monitor_output,\n",
+        "    ], check=False).returncode\n",
+        "\n",
+        "def pull_once() -> bool:\n",
+        "    return run([\n",
+        "        \"uv\", \"run\", \"python\", \"scripts/pull_training_artifacts.py\",\n",
+        "        \"--artifact-repo-id\", ARTIFACT_REPO_ID,\n",
+        "    ], check=False).returncode == 0\n",
+        "\n",
+        "pulled = False\n",
+        "if RUN_REMOTE_TRAINING and WAIT_FOR_REMOTE_TRAINING:\n",
+        "    deadline = time.time() + REMOTE_TIMEOUT_HOURS * 3600\n",
+        "    attempt = 0\n",
+        "    while time.time() < deadline:\n",
+        "        attempt += 1\n",
+        "        print(f\"Remote poll {attempt}\")\n",
+        "        monitor_once()\n",
+        "        pulled = pull_once()\n",
+        "        if pulled:\n",
+        "            print(\"Remote training artifacts pulled successfully.\")\n",
+        "            break\n",
+        "        print(f\"Artifacts not ready yet. Sleeping {REMOTE_POLL_SECONDS} seconds.\")\n",
+        "        time.sleep(REMOTE_POLL_SECONDS)\n",
+        "    if not pulled:\n",
+        "        raise TimeoutError(\"Remote training did not produce pullable artifacts before timeout.\")\n",
+        "else:\n",
+        "    monitor_once()\n",
+        "    pulled = pull_once()\n",
+        "    print(f\"Single pull attempt success: {pulled}\")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 6) Generate Reports, Charts, And Evidence Bundles\n",
+        "\n",
+        "This creates SFT-vs-GRPO charts, Qwen model comparison charts, reward component bars, anti-hacking/overfit checks, basic-LLM-vs-PolyGuard evidence, action traces, and curated submission evidence folders."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "run([\"uv\", \"run\", \"python\", \"scripts/generate_hf_training_report.py\", \"--mode\", os.getenv(\"POLYGUARD_TRAINING_MODE\", \"full\")], check=False)\n",
+        "run([\"uv\", \"run\", \"python\", \"scripts/evaluate_policy_ablations.py\", \"--episodes\", os.getenv(\"POLYGUARD_ABLATION_EPISODES\", \"8\")], check=False)\n",
+        "run([\n",
+        "    \"uv\", \"run\", \"python\", \"scripts/generate_submission_evidence.py\",\n",
+        "    \"--models\", os.getenv(\"POLYGUARD_EVIDENCE_MODELS\", \"qwen-qwen2-5-0-5b-instruct,qwen-qwen2-5-1-5b-instruct\"),\n",
+        "    \"--artifact-repo-id\", ARTIFACT_REPO_ID,\n",
+        "    \"--training-space-url\", f\"https://{TRAINING_SPACE_REPO_ID.replace('/', '-').lower()}.hf.space\",\n",
+        "    \"--episodes\", os.getenv(\"POLYGUARD_EVIDENCE_EPISODES\", \"8\"),\n",
+        "], check=False)\n",
+        "run([\"uv\", \"run\", \"python\", \"scripts/build_improvement_evidence_bundle.py\"], check=False)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 7) Activate A Model For Product Inference And Validate Post-Save Inference\n",
+        "\n",
+        "The app reads `checkpoints/active/active_model_manifest.json`. The default active run is Qwen 0.5B because it is the smallest practical implementation target; switch `POLYGUARD_ACTIVE_RUN_ID` to the 1.5B or 3B run after those artifacts are pulled."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "ACTIVE_RUN_ID = os.getenv(\"POLYGUARD_ACTIVE_RUN_ID\", \"qwen-qwen2-5-0-5b-instruct\")\n",
+        "run([\n",
+        "    \"uv\", \"run\", \"python\", \"scripts/activate_sweep_model.py\",\n",
+        "    \"--source\", \"sweep\",\n",
+        "    \"--run-id\", ACTIVE_RUN_ID,\n",
+        "    \"--preferred-artifact\", os.getenv(\"POLYGUARD_PREFERRED_ARTIFACT\", \"grpo_adapter\"),\n",
+        "], check=False)\n",
+        "run([\"uv\", \"run\", \"python\", \"scripts/test_inference_postsave.py\", \"--samples\", os.getenv(\"POLYGUARD_INFERENCE_SAMPLES\", \"3\")], check=False)\n",
+        "run([\"uv\", \"run\", \"python\", \"scripts/benchmark_inference.py\"], check=False)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 8) Deploy The Product OpenEnv Space\n",
+        "\n",
+        "This deploys the FastAPI/OpenEnv product Space. It is separate from the private GPU training Space."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "if DEPLOY_PRODUCT_SPACE:\n",
+        "    product_cmd = [\"uv\", \"run\", \"python\", \"scripts/deploy_space_api.py\", \"--repo-id\", PRODUCT_SPACE_REPO_ID]\n",
+        "    if PRODUCT_SPACE_PRIVATE:\n",
+        "        product_cmd.append(\"--private\")\n",
+        "    run(product_cmd)\n",
+        "    runtime_url = f\"https://{PRODUCT_SPACE_REPO_ID.replace('/', '-').lower()}.hf.space\"\n",
+        "    run([\"uv\", \"run\", \"openenv\", \"validate\", \"--url\", runtime_url], check=False)\n",
+        "    print(f\"Product Space: https://huggingface.co/spaces/{PRODUCT_SPACE_REPO_ID}\")\n",
+        "    print(f\"Runtime URL: {runtime_url}\")\n",
+        "else:\n",
+        "    print(\"Product Space deploy skipped by POLYGUARD_DEPLOY_PRODUCT_SPACE=0\")\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## 9) Final Acceptance Gate And Output Summary"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "run([\"uv\", \"run\", \"python\", \"scripts/acceptance_gate.py\"], check=False)\n",
+        "\n",
+        "summary = {\n",
+        "    \"training_space\": f\"https://huggingface.co/spaces/{TRAINING_SPACE_REPO_ID}\",\n",
+        "    \"artifact_repo\": f\"https://huggingface.co/{ARTIFACT_REPO_ID}\",\n",
+        "    \"product_space\": f\"https://huggingface.co/spaces/{PRODUCT_SPACE_REPO_ID}\",\n",
+        "    \"reports\": [\n",
+        "        \"outputs/reports/hf_sweep_summary.json\",\n",
+        "        \"outputs/reports/anti_hacking_overfit_report.json\",\n",
+        "        \"outputs/reports/postsave_inference.json\",\n",
+        "        \"docs/results/submission_evidence_qwen_0_5b_1_5b/README.md\",\n",
+        "        \"docs/results/model_improvement_evidence_qwen_0_5b_1_5b/README.md\",\n",
+        "    ],\n",
+        "    \"plots_dir\": \"outputs/plots\",\n",
+        "    \"active_model_manifest\": \"checkpoints/active/active_model_manifest.json\",\n",
+        "}\n",
+        "print(json.dumps(summary, indent=2))\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.11"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

README.md

@@ -1,10 +1,12 @@
 ---
-title: Polyguard Openenv Workbench
-emoji: 📉
+title: PolyGuard OpenEnv
+emoji: 🛡️
 colorFrom: blue
-colorTo: red
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+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.

README_HF_SPACE.md

@@ -0,0 +1,12 @@
+---
+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.

__init__.py

@@ -0,0 +1,5 @@
+"""Root OpenEnv package shim for POLYGUARD-OPENENV."""
+
+from app.env.env_core import PolyGuardEnv
+
+__all__ = ["PolyGuardEnv"]

app/__init__.py

@@ -0,0 +1 @@
+"""POLYGUARD-RL application package."""

app/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Agent package."""
+
+from app.agents.orchestrator import Orchestrator
+
+__all__ = ["Orchestrator"]

app/agents/candidate_agent.py

@@ -0,0 +1,14 @@
+"""Candidate generation agent."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardState
+from app.models.policy.candidate_builder import build_candidates
+
+
+class CandidateAgent:
+    name = "CandidateAgent"
+
+    def run(self, state: PolyGuardState) -> dict:
+        candidates = build_candidates(state)
+        return {"candidates": [c.model_dump(mode="json") for c in candidates]}

app/agents/critic_agent.py

@@ -0,0 +1,43 @@
+"""Safety critic agent."""
+
+from __future__ import annotations
+
+from app.common.enums import ActionType, DecisionMode, DoseBucket
+from app.common.types import PolyGuardAction, PolyGuardState
+from app.env.verifier import verify_action_legality
+
+
+class CriticAgent:
+    name = "CriticAgent"
+
+    def run(self, state: PolyGuardState, proposed: PolyGuardAction) -> dict:
+        report = verify_action_legality(state, proposed)
+        if report.legal:
+            report_payload = report.model_dump(mode="json")
+            return {
+                "approved": True,
+                "report": report_payload,
+                "final_action": proposed,
+                "legal": True,
+                "violations": report_payload.get("violations", []),
+            }
+        fallback = PolyGuardAction(
+            mode=DecisionMode.REVIEW,
+            action_type=ActionType.REQUEST_SPECIALIST_REVIEW,
+            target_drug=None,
+            replacement_drug=None,
+            dose_bucket=DoseBucket.NA,
+            taper_days=None,
+            monitoring_plan="critic_veto",
+            candidate_id="cand_veto_fallback",
+            confidence=0.62,
+            rationale_brief=f"Critic veto: {', '.join(report.violations)}",
+        )
+        report_payload = report.model_dump(mode="json")
+        return {
+            "approved": False,
+            "report": report_payload,
+            "final_action": fallback,
+            "legal": False,
+            "violations": report_payload.get("violations", []),
+        }

app/agents/critic_safety_agent.py

@@ -0,0 +1,11 @@
+"""Canonical CriticSafety agent module.
+
+This file preserves required naming while reusing the current critic
+implementation.
+"""
+
+from __future__ import annotations
+
+from app.agents.critic_agent import CriticAgent as CriticSafetyAgent
+
+__all__ = ["CriticSafetyAgent"]

app/agents/dosing_agent.py

@@ -0,0 +1,52 @@
+"""Dosing analysis agent."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardState
+from app.knowledge.drug_catalog import DRUG_CLASSES
+from app.models.dosing.dose_policy_features import build_dose_features
+from app.models.dosing.infer import infer_dosing_quality
+from app.models.dosing.pkpd_state import PKPDState
+from app.models.dosing.surrogate_pkpd import step_pkpd
+
+
+class DosingAgent:
+    name = "DosingAgent"
+
+    def run(self, state: PolyGuardState) -> dict:
+        sensitive_classes = {"anticoagulant", "sedative", "glucose_lowering"}
+        dose_sensitive = [
+            m.drug
+            for m in state.patient.medications
+            if DRUG_CLASSES.get(m.drug) in sensitive_classes
+        ][:3]
+        analyses: list[dict] = []
+        for drug in dose_sensitive:
+            feats = build_dose_features(state.patient, drug)
+            base_state = PKPDState(
+                effect_level=min(1.0, 0.35 + feats["adherence"] * 0.45),
+                toxicity_level=min(1.0, 0.08 + feats["organ_stress"] * 0.4),
+                underdose_risk=max(0.0, 1.0 - (0.35 + feats["adherence"] * 0.45)),
+                organ_stress=feats["organ_stress"],
+                interaction_load=feats["interaction_load"],
+            )
+            lower = infer_dosing_quality(step_pkpd(base_state, dose_delta=-0.2, organ_factor=feats["organ_stress"], interaction_factor=feats["interaction_load"]))
+            hold = infer_dosing_quality(step_pkpd(base_state, dose_delta=0.0, organ_factor=feats["organ_stress"], interaction_factor=feats["interaction_load"]))
+            higher = infer_dosing_quality(step_pkpd(base_state, dose_delta=0.2, organ_factor=feats["organ_stress"], interaction_factor=feats["interaction_load"]))
+            analyses.append(
+                {
+                    "drug": drug,
+                    "features": feats,
+                    "options": {
+                        "reduce": lower,
+                        "hold": hold,
+                        "increase": higher,
+                    },
+                }
+            )
+        return {
+            "dose_sensitive_drugs": dose_sensitive,
+            "dosing_active": bool(dose_sensitive),
+            "recommend_mode": "DOSE_OPT" if dose_sensitive else "REGIMEN_OPT",
+            "analyses": analyses,
+        }

app/agents/evidence_agent.py

@@ -0,0 +1,14 @@
+"""Evidence retrieval agent."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardState
+from app.knowledge.evidence_retriever import retrieve_evidence
+
+
+class EvidenceAgent:
+    name = "EvidenceAgent"
+
+    def run(self, state: PolyGuardState) -> dict:
+        query = " ".join(state.patient.comorbidities + [m.drug for m in state.patient.medications[:2]])
+        return {"evidence": retrieve_evidence(query=query, top_k=3)}

app/agents/explainer_agent.py

@@ -0,0 +1,22 @@
+"""Explanation agent."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardAction, PolyGuardState
+
+
+class ExplainerAgent:
+    name = "ExplainerAgent"
+
+    def run(self, state: PolyGuardState, action: PolyGuardAction, critic_report: dict) -> dict:
+        return {
+            "explanation": (
+                f"Action {action.action_type.value} selected for mode {action.mode.value}. "
+                f"Burden score={state.burden_score:.3f}, meds={len(state.patient.medications)}. "
+                f"Critic legal={critic_report.get('legal', False)}."
+            ),
+            "grounded_facts": {
+                "burden_score": state.burden_score,
+                "polypharmacy_count": len(state.patient.medications),
+            },
+        }

app/agents/graph_agent.py

@@ -0,0 +1,28 @@
+"""Graph safety agent."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardState
+from app.knowledge.ddi_knowledge import top_risky_pairs
+from app.models.graph.infer import infer_graph_risk
+
+
+class GraphSafetyAgent:
+    name = "GraphSafetyAgent"
+
+    def run(self, state: PolyGuardState) -> dict:
+        drugs = [m.drug for m in state.patient.medications]
+        risk = infer_graph_risk(drugs)
+        top_pairs = top_risky_pairs(drugs)
+        triples = []
+        if len(drugs) >= 3:
+            triples = [
+                [drugs[i], drugs[i + 1], drugs[i + 2]]
+                for i in range(min(2, len(drugs) - 2))
+            ]
+        return {
+            **risk,
+            "top_dangerous_pairs": top_pairs[:5],
+            "top_dangerous_triples": triples,
+            "mechanism_tags": list(risk.get("side_effect_probs", {}).keys())[:5],
+        }

app/agents/graph_safety_agent.py

@@ -0,0 +1,11 @@
+"""Canonical GraphSafety agent module.
+
+This file is kept for required path compatibility and re-exports the
+implementation from ``graph_agent.py``.
+"""
+
+from __future__ import annotations
+
+from app.agents.graph_agent import GraphSafetyAgent
+
+__all__ = ["GraphSafetyAgent"]

app/agents/medrec_agent.py

@@ -0,0 +1,22 @@
+"""Medication reconciliation agent."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardState
+from app.knowledge.drug_catalog import canonicalize_drug_name
+
+
+class MedRecAgent:
+    name = "MedRecAgent"
+
+    def run(self, state: PolyGuardState) -> dict:
+        normalized = []
+        duplicates = set()
+        seen = set()
+        for med in state.patient.medications:
+            med.drug = canonicalize_drug_name(med.drug)
+            normalized.append(med.drug)
+            if med.drug in seen:
+                duplicates.add(med.drug)
+            seen.add(med.drug)
+        return {"normalized_meds": normalized, "duplicates": sorted(duplicates)}

app/agents/orchestrator.py

@@ -0,0 +1,151 @@
+"""Multi-agent orchestration graph."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from app.agents.candidate_agent import CandidateAgent
+from app.agents.critic_agent import CriticAgent
+from app.agents.dosing_agent import DosingAgent
+from app.agents.evidence_agent import EvidenceAgent
+from app.agents.explainer_agent import ExplainerAgent
+from app.agents.graph_agent import GraphSafetyAgent
+from app.agents.medrec_agent import MedRecAgent
+from app.agents.planner_agent import PlannerAgent
+from app.agents.supervisor_agent import SupervisorAgent
+from app.common.enums import CoordinationMode
+from app.common.types import CandidateAction, PolyGuardAction
+from app.env.env_core import PolyGuardEnv
+from app.models.baselines.contextual_bandit_policy import ContextualBanditPolicy
+
+
+class Orchestrator:
+    def __init__(self, env: PolyGuardEnv, coordination_mode: CoordinationMode = CoordinationMode.SEQUENTIAL) -> None:
+        self.env = env
+        self.coordination_mode = coordination_mode
+        self.medrec = MedRecAgent()
+        self.evidence = EvidenceAgent()
+        self.graph = GraphSafetyAgent()
+        self.dosing = DosingAgent()
+        self.candidate = CandidateAgent()
+        self.supervisor = SupervisorAgent()
+        self.planner = PlannerAgent()
+        self.critic = CriticAgent()
+        self.explainer = ExplainerAgent()
+        bandit_algo = os.getenv("POLYGUARD_BANDIT_ALGO", "linucb").strip().lower()
+        if bandit_algo not in {"linucb", "thompson"}:
+            bandit_algo = "linucb"
+        self.bandit = ContextualBanditPolicy(
+            algorithm=bandit_algo,  # type: ignore[arg-type]
+            alpha=float(os.getenv("POLYGUARD_BANDIT_ALPHA", "0.55")),
+            epsilon=float(os.getenv("POLYGUARD_BANDIT_EPSILON", "0.1")),
+            seed=int(os.getenv("POLYGUARD_BANDIT_SEED", "42")),
+        )
+        self.policy_stack = os.getenv("POLYGUARD_POLICY_STACK", "llm+bandit").strip().lower()
+        self.bandit_top_k = int(os.getenv("POLYGUARD_BANDIT_TOP_K", "3"))
+
+    def set_mode(self, coordination_mode: CoordinationMode) -> None:
+        self.coordination_mode = coordination_mode
+
+    def run_step(self, coordination_mode: str | None = None) -> dict[str, Any]:
+        if coordination_mode is not None:
+            self.coordination_mode = CoordinationMode(coordination_mode)
+        state = self.env.state
+        medrec_out = self.medrec.run(state)
+        evidence_out = self.evidence.run(state)
+        graph_out = self.graph.run(state)
+        dosing_out = self.dosing.run(state)
+        candidate_out = self.candidate.run(state)
+        candidates = [CandidateAction.model_validate(item) for item in candidate_out["candidates"]]
+
+        supervisor_out = self.supervisor.run(state, dosing_active=dosing_out["dosing_active"])
+        planner_candidates = [c for c in candidates if c.mode.value == supervisor_out["mode"]] or candidates
+        if self.coordination_mode == CoordinationMode.SUPERVISOR_ROUTED and supervisor_out["mode"] == "REVIEW":
+            planner_candidates = [c for c in candidates if c.mode.value == "REVIEW"] or planner_candidates
+
+        candidate_by_id = {item.candidate_id: item for item in planner_candidates}
+        bandit_proposals = self.bandit.propose(planner_candidates, top_k=self.bandit_top_k)
+        bandit_candidates = [candidate_by_id[item.candidate_id] for item in bandit_proposals if item.candidate_id in candidate_by_id]
+        if not bandit_candidates:
+            bandit_candidates = planner_candidates
+
+        if self.policy_stack == "bandit-only":
+            selected = bandit_candidates[0]
+            proposed = PolyGuardAction(
+                mode=selected.mode,
+                action_type=selected.action_type,
+                target_drug=selected.target_drug,
+                replacement_drug=selected.replacement_drug,
+                dose_bucket=selected.dose_bucket,
+                taper_days=selected.taper_days,
+                monitoring_plan=selected.monitoring_plan,
+                candidate_id=selected.candidate_id,
+                confidence=max(0.45, 1.0 - selected.uncertainty_score),
+                rationale_brief="Bandit-only policy selected top contextual candidate.",
+            )
+        elif self.policy_stack == "llm-only":
+            proposed = self.planner.run(candidates=planner_candidates, mode=supervisor_out["mode"])
+        else:
+            proposed = self.planner.run(
+                candidates=bandit_candidates,
+                mode=supervisor_out["mode"],
+                provider_prompt={
+                    "coordination_mode": self.coordination_mode.value,
+                    "policy_stack": self.policy_stack,
+                    "candidate_count": len(bandit_candidates),
+                    "sub_environment": state.sub_environment.value,
+                },
+            )
+
+        critic_out = self.critic.run(state, proposed)
+        final_action: PolyGuardAction = critic_out["final_action"]
+        replan_triggered = False
+        debate_rounds = 0
+
+        if self.coordination_mode in {CoordinationMode.REPLAN_ON_VETO, CoordinationMode.LIGHT_DEBATE} and not critic_out["approved"]:
+            replan_triggered = True
+            review_candidates = [c for c in candidates if c.mode.value == "REVIEW"] or candidates
+            proposed = self.planner.run(candidates=review_candidates, mode="REVIEW")
+            critic_out = self.critic.run(state, proposed)
+            final_action = critic_out["final_action"]
+            debate_rounds = 1
+
+        if self.coordination_mode == CoordinationMode.LIGHT_DEBATE and critic_out["approved"] and proposed.action_type != final_action.action_type:
+            debate_rounds = 2
+
+        obs, reward, done, info = self.env.step(final_action)
+        selected_for_update = candidate_by_id.get(final_action.candidate_id)
+        if selected_for_update is not None:
+            self.bandit.update(selected_for_update, reward=reward)
+
+        explanation_out = self.explainer.run(state, final_action, critic_out["report"])
+        return {
+            "medrec": medrec_out,
+            "evidence": evidence_out,
+            "graph": graph_out,
+            "dosing": dosing_out,
+            "supervisor": supervisor_out,
+            "proposed_action": proposed.model_dump(mode="json"),
+            "critic": critic_out["report"],
+            "final_action": final_action.model_dump(mode="json"),
+            "observation": obs.model_dump(mode="json"),
+            "reward": reward,
+            "done": done,
+            "info": info,
+            "explanation": explanation_out,
+            "coordination_mode": self.coordination_mode.value,
+            "policy_stack": self.policy_stack,
+            "bandit_topk": [item.candidate_id for item in bandit_candidates],
+            "bandit_scores": [
+                {
+                    "candidate_id": item.candidate_id,
+                    "score": item.score,
+                    "exploration_bonus": item.exploration_bonus,
+                    "algorithm": item.algorithm,
+                }
+                for item in bandit_proposals
+            ],
+            "replan_triggered": replan_triggered,
+            "debate_rounds": debate_rounds,
+        }

app/agents/planner_agent.py

@@ -0,0 +1,44 @@
+"""Planner agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.common.types import CandidateAction, PolyGuardAction
+from app.models.policy.provider_runtime import PolicyProviderRouter, default_provider_preference
+from app.models.policy.safety_ranker import rank_candidates
+
+
+class PlannerAgent:
+    name = "PlannerAgent"
+
+    def __init__(self) -> None:
+        self.provider_router = PolicyProviderRouter()
+
+    def run(
+        self,
+        candidates: list[CandidateAction],
+        mode: str,
+        provider_prompt: dict[str, Any] | None = None,
+        provider_preference: tuple[str, ...] | None = None,
+    ) -> PolyGuardAction:
+        filtered = [c for c in candidates if c.mode.value == mode] or candidates
+        selection = self.provider_router.select_candidate(
+            candidates=filtered,
+            prompt=provider_prompt or {"mode": mode},
+            provider_preference=provider_preference or default_provider_preference(),
+        )
+        by_id = {item.candidate_id: item for item in filtered}
+        top = by_id.get(selection.candidate_id, rank_candidates(filtered)[0])
+        return PolyGuardAction(
+            mode=top.mode,
+            action_type=top.action_type,
+            target_drug=top.target_drug,
+            replacement_drug=top.replacement_drug,
+            dose_bucket=top.dose_bucket,
+            taper_days=top.taper_days,
+            monitoring_plan=top.monitoring_plan,
+            candidate_id=top.candidate_id,
+            confidence=max(0.45, 1.0 - top.uncertainty_score),
+            rationale_brief=selection.rationale,
+        )

app/agents/supervisor_agent.py

@@ -0,0 +1,23 @@
+"""Supervisor agent."""
+
+from __future__ import annotations
+
+from app.common.enums import DecisionMode
+from app.common.types import PolyGuardState
+from app.models.policy.uncertainty import estimate_uncertainty
+
+
+class SupervisorAgent:
+    name = "SupervisorAgent"
+
+    def run(self, state: PolyGuardState, dosing_active: bool) -> dict:
+        uncertainty = estimate_uncertainty(state)
+        if uncertainty > 0.72:
+            mode = DecisionMode.REVIEW
+        elif state.sub_environment.value == "PRECISION_DOSING":
+            mode = DecisionMode.DOSE_OPT
+        elif dosing_active:
+            mode = DecisionMode.DOSE_OPT
+        else:
+            mode = DecisionMode.REGIMEN_OPT
+        return {"mode": mode.value, "uncertainty": uncertainty, "sub_environment": state.sub_environment.value}

app/api/__init__.py

@@ -0,0 +1,46 @@
+"""API application entrypoint."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.common.config import load_project_env
+from app.api.routes import router
+
+load_project_env()
+
+_cors_local = [
+    "http://127.0.0.1:5173",
+    "http://localhost:5173",
+]
+_extra = os.getenv("POLYGUARD_CORS_ORIGINS", "").strip()
+if _extra and _extra != "*":
+    _cors_local = _cors_local + [o.strip() for o in _extra.split(",") if o.strip()]
+_hf_space_regex = None
+if os.getenv("POLYGUARD_ALLOW_HF_SPACE_CORS", "").lower() in {"1", "true", "yes", "on"}:
+    _hf_space_regex = r"https://.*\.hf\.space"
+
+app = FastAPI(title="POLYGUARD-RL API", version="0.1.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_cors_local,
+    allow_origin_regex=_hf_space_regex,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+app.include_router(router)
+
+
+def main() -> None:
+    host = os.getenv("POLYGUARD_API_HOST", "127.0.0.1")
+    port = int(os.getenv("POLYGUARD_API_PORT", "8200"))
+    uvicorn.run("app.api:app", host=host, port=port, reload=False)
+
+
+if __name__ == "__main__":
+    main()

app/api/__main__.py

@@ -0,0 +1,7 @@
+"""Run API with `python -m app.api`."""
+
+from app.api import main
+
+
+if __name__ == "__main__":
+    main()

app/api/dependencies.py

@@ -0,0 +1,11 @@
+"""API dependencies."""
+
+from __future__ import annotations
+
+from app.api.service import APIService
+
+_SERVICE = APIService()
+
+
+def get_service() -> APIService:
+    return _SERVICE

app/api/main.py

@@ -0,0 +1,10 @@
+"""Canonical API module path.
+
+Keeps compatibility with required file path while reusing ``app.api`` app.
+"""
+
+from __future__ import annotations
+
+from app.api import app, main
+
+__all__ = ["app", "main"]

app/api/routes.py

@@ -0,0 +1,139 @@
+"""API routes."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.dependencies import get_service
+from app.api.schemas import (
+    BatchInferRequest,
+    EvidenceQueryRequest,
+    OrchestrateRequest,
+    ResetRequest,
+    StepCandidateRequest,
+    StepRequest,
+)
+from app.api.service import APIService
+
+router = APIRouter()
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@router.post("/env/reset")
+def env_reset(payload: ResetRequest, service: APIService = Depends(get_service)) -> dict:
+    try:
+        return service.reset(**payload.model_dump(mode="json"))
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/env/step")
+def env_step(payload: StepRequest, service: APIService = Depends(get_service)) -> dict:
+    return service.step(payload.model_dump(mode="json"))
+
+
+@router.post("/env/step_candidate")
+def env_step_candidate(payload: StepCandidateRequest, service: APIService = Depends(get_service)) -> dict:
+    result = service.step_candidate(
+        candidate_id=payload.candidate_id,
+        confidence=payload.confidence,
+        rationale_brief=payload.rationale_brief,
+    )
+    if result is None:
+        raise HTTPException(status_code=404, detail=f"Candidate {payload.candidate_id!r} is not legal in this state.")
+    return result
+
+
+@router.get("/env/catalog")
+def env_catalog(service: APIService = Depends(get_service)) -> dict:
+    return service.catalog()
+
+
+@router.get("/env/state")
+def env_state(service: APIService = Depends(get_service)) -> dict:
+    return service.env.get_state()
+
+
+@router.get("/env/trace")
+def env_trace(service: APIService = Depends(get_service)) -> list[dict]:
+    return service.env.get_trace()
+
+
+@router.get("/env/legal_actions")
+def env_legal_actions(service: APIService = Depends(get_service)) -> list[dict]:
+    return service.env.get_legal_actions()
+
+
+@router.get("/env/reward_breakdown")
+def env_reward_breakdown(service: APIService = Depends(get_service)) -> dict:
+    return service.env.get_reward_breakdown()
+
+
+@router.get("/env/uncertainty")
+def env_uncertainty(service: APIService = Depends(get_service)) -> dict:
+    return service.env.get_uncertainty_report().model_dump(mode="json")
+
+
+@router.post("/agents/orchestrate")
+def agents_orchestrate(
+    payload: OrchestrateRequest = OrchestrateRequest(),
+    service: APIService = Depends(get_service),
+) -> dict:
+    return service.orchestrate(coordination_mode=payload.coordination_mode)
+
+
+@router.post("/policy/infer")
+def policy_infer(service: APIService = Depends(get_service)) -> dict:
+    return service.infer_policy()
+
+
+@router.get("/policy/model_status")
+def policy_model_status(service: APIService = Depends(get_service)) -> dict:
+    return service.model_status()
+
+
+@router.post("/policy/batch_infer")
+def policy_batch_infer(
+    payload: BatchInferRequest = BatchInferRequest(),
+    service: APIService = Depends(get_service),
+) -> list[dict]:
+    return service.batch_infer(batch_size=payload.batch_size)
+
+
+@router.post("/eval/run_baselines")
+def eval_baselines(service: APIService = Depends(get_service)) -> dict:
+    return service.run_baselines()
+
+
+@router.post("/eval/run_policy")
+def eval_run_policy(service: APIService = Depends(get_service)) -> dict:
+    return service.run_policy_eval()
+
+
+@router.post("/eval/run_dosing")
+def eval_run_dosing(service: APIService = Depends(get_service)) -> dict:
+    return service.run_dosing_eval()
+
+
+@router.get("/metrics/training")
+def metrics_training(service: APIService = Depends(get_service)) -> dict:
+    return service.get_metrics()
+
+
+@router.get("/cases/sample")
+def cases_sample(service: APIService = Depends(get_service)) -> dict:
+    return service.sample_case()
+
+
+@router.get("/cases/search")
+def cases_search(q: str, service: APIService = Depends(get_service)) -> list[dict]:
+    return service.search_cases(q)
+
+
+@router.post("/evidence/query")
+def evidence_query(payload: EvidenceQueryRequest, service: APIService = Depends(get_service)) -> list[dict]:
+    return service.evidence_query(query=payload.query, top_k=payload.top_k)

app/api/schemas.py

@@ -0,0 +1,57 @@
+"""API schemas."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.common.enums import ActionType, DecisionMode, Difficulty, DoseBucket, SubEnvironment
+
+
+class StrictSchema(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ResetRequest(StrictSchema):
+    task_id: Optional[str] = None
+    seed: Optional[int] = None
+    difficulty: Optional[Difficulty] = None
+    sub_environment: Optional[SubEnvironment] = None
+    scenario_id: Optional[str] = None
+    patient_id: Optional[str] = None
+
+
+class StepRequest(StrictSchema):
+    mode: DecisionMode
+    action_type: ActionType
+    target_drug: Optional[str] = None
+    replacement_drug: Optional[str] = None
+    dose_bucket: DoseBucket
+    taper_days: Optional[int] = None
+    monitoring_plan: Optional[str] = None
+    evidence_query: Optional[str] = None
+    new_drug_name: Optional[str] = None
+    candidate_components: list[str] = Field(default_factory=list)
+    candidate_id: str
+    confidence: float
+    rationale_brief: str
+
+
+class StepCandidateRequest(StrictSchema):
+    candidate_id: str
+    confidence: float
+    rationale_brief: str
+
+
+class OrchestrateRequest(StrictSchema):
+    coordination_mode: Optional[str] = None
+
+
+class BatchInferRequest(StrictSchema):
+    batch_size: int = 4
+
+
+class EvidenceQueryRequest(StrictSchema):
+    query: str
+    top_k: int = 5

app/api/service.py

@@ -0,0 +1,219 @@
+"""API service layer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from app.agents.orchestrator import Orchestrator
+from app.env.catalog import apply_task_preset, env_catalog
+from app.env.env_core import PolyGuardEnv
+from app.evaluation.benchmark_report import build_benchmark_report
+from app.evaluation.dosing_eval import dosing_eval
+from app.knowledge.evidence_retriever import retrieve_evidence
+from app.models.retrieval.retriever import retrieve
+from app.models.policy.provider_runtime import PolicyProviderRouter, default_provider_preference
+from app.models.baselines import (
+    choose_beam_search,
+    choose_contextual_bandit,
+    choose_contextual_bandit_topk,
+    choose_greedy,
+    choose_no_change,
+    choose_rules_only,
+)
+from app.training import train_dosing_grpo, train_planner_grpo, train_supervisor_grpo
+
+
+class APIService:
+    def __init__(self) -> None:
+        self.env = PolyGuardEnv()
+        self.orchestrator = Orchestrator(self.env)
+        self.policy_router = PolicyProviderRouter()
+        self.training_metrics: dict[str, Any] = {}
+        self.root = Path(__file__).resolve().parents[2]
+
+    def reset(self, **kwargs: Any) -> dict[str, Any]:
+        kwargs = apply_task_preset(dict(kwargs))
+        obs = self.env.reset(**kwargs)
+        return obs.model_dump(mode="json")
+
+    def step(self, action: dict[str, Any]) -> dict[str, Any]:
+        obs, reward, done, info = self.env.step(action)
+        reason = str(info.get("termination_reason", "")) if isinstance(info, dict) else ""
+        truncated = reason in {"wall_clock_timeout", "step_timeout", "step_budget_exhausted"}
+        return {
+            "observation": obs.model_dump(mode="json"),
+            "reward": reward,
+            "done": done,
+            "terminated": done,
+            "truncated": truncated,
+            "info": info,
+        }
+
+    def catalog(self) -> dict[str, Any]:
+        return env_catalog()
+
+    def step_candidate(self, candidate_id: str, confidence: float, rationale_brief: str) -> dict[str, Any] | None:
+        for action in self.env.get_legal_actions():
+            if action.get("candidate_id") != candidate_id:
+                continue
+            payload = dict(action)
+            payload["confidence"] = confidence
+            payload["rationale_brief"] = rationale_brief
+            return self.step(payload)
+        return None
+
+    def orchestrate(self, coordination_mode: str | None = None) -> dict[str, Any]:
+        return self.orchestrator.run_step(coordination_mode=coordination_mode)
+
+    def infer_policy(self) -> dict[str, Any]:
+        legal = self.env.get_legal_actions()
+        if not legal:
+            return {}
+        candidate_payloads = [
+            item for item in self.env.get_candidate_actions() if bool(item.get("legality_precheck", False))
+        ]
+        if not candidate_payloads:
+            return legal[0]
+        candidates = [self._candidate_obj(item) for item in candidate_payloads]
+        state = self.env.state
+        selection = self.policy_router.select_candidate(
+            candidates=candidates,
+            prompt={
+                "patient_id": state.patient.patient_id,
+                "difficulty": state.difficulty.value,
+                "sub_environment": state.sub_environment.value,
+                "step_count": state.step_count,
+            },
+            provider_preference=default_provider_preference(),
+        )
+        selected = next((item for item in legal if item.get("candidate_id") == selection.candidate_id), legal[0])
+        payload = dict(selected)
+        payload["policy_selection"] = {
+            "provider": selection.provider,
+            "candidate_id": selection.candidate_id,
+            "rationale": selection.rationale,
+            "latency_ms": round(selection.latency_ms, 3),
+            "raw_output": selection.raw_output,
+        }
+        return payload
+
+    def model_status(self) -> dict[str, Any]:
+        return self.policy_router.model_status()
+
+    def batch_infer(self, batch_size: int = 4) -> list[dict[str, Any]]:
+        legal = self.env.get_legal_actions()
+        return legal[:batch_size]
+
+    def run_baselines(self) -> dict[str, Any]:
+        candidates = [c for c in self.env.get_candidate_actions() if c.get("legality_precheck")]
+        if not candidates:
+            self.env.reset()
+            candidates = [c for c in self.env.get_candidate_actions() if c.get("legality_precheck")]
+        baseline_results = {
+            "no_change": choose_no_change().model_dump(mode="json"),
+            "rules_only": choose_rules_only([self._candidate_obj(c) for c in candidates]).model_dump(mode="json"),
+            "greedy": choose_greedy([self._candidate_obj(c) for c in candidates]).model_dump(mode="json"),
+            "contextual_bandit": choose_contextual_bandit([self._candidate_obj(c) for c in candidates]).model_dump(mode="json"),
+            "contextual_bandit_topk": [
+                {
+                    "candidate_id": item.candidate_id,
+                    "score": item.score,
+                    "exploration_bonus": item.exploration_bonus,
+                    "algorithm": item.algorithm,
+                }
+                for item in choose_contextual_bandit_topk([self._candidate_obj(c) for c in candidates], top_k=3)
+            ],
+            "beam_search": choose_beam_search([self._candidate_obj(c) for c in candidates]).model_dump(mode="json"),
+        }
+        return baseline_results
+
+    def run_policy_eval(self) -> dict[str, Any]:
+        out = build_benchmark_report(Path("outputs/reports/benchmark_report.txt"))
+        return out
+
+    def run_dosing_eval(self) -> dict[str, Any]:
+        return dosing_eval()
+
+    def run_training(self) -> dict[str, Any]:
+        out_dir = Path("checkpoints")
+        out_dir.mkdir(parents=True, exist_ok=True)
+        self.training_metrics = {
+            "supervisor": train_supervisor_grpo(episodes=4, checkpoint_dir=out_dir),
+            "planner": train_planner_grpo(episodes=6, checkpoint_dir=out_dir),
+            "dosing": train_dosing_grpo(episodes=4, checkpoint_dir=out_dir),
+        }
+        return self.training_metrics
+
+    def get_metrics(self) -> dict[str, Any]:
+        if self.training_metrics:
+            if "planner" in self.training_metrics:
+                merged = dict(self.training_metrics["planner"])
+                merged["model_metrics"] = self.training_metrics
+                return merged
+            return self.training_metrics
+        reports_dir = Path("outputs/reports")
+        metrics: dict[str, Any] = {}
+        for name in ["supervisor_grpo", "planner_grpo", "dosing_grpo"]:
+            path = reports_dir / f"{name}.json"
+            if path.exists():
+                import json
+
+                metrics[name] = json.loads(path.read_text(encoding="utf-8"))
+        self.training_metrics = metrics
+        if "planner_grpo" in metrics:
+            merged = dict(metrics["planner_grpo"])
+            merged["model_metrics"] = metrics
+            return merged
+        return metrics
+
+    def sample_case(self) -> dict[str, Any]:
+        obs = self.env.reset()
+        return obs.model_dump(mode="json")
+
+    def search_cases(self, query: str) -> list[dict[str, Any]]:
+        index_file = self.root / "data" / "retrieval_index" / "index.json"
+        hits = retrieve(index_file=index_file, query=query, top_k=5)
+        if hits:
+            return [
+                {
+                    "patient_id": Path(item.get("path", f"case_{idx}")).stem,
+                    "query": query,
+                    "source_path": item.get("path", ""),
+                    "snippet": str(item.get("text", ""))[:280],
+                }
+                for idx, item in enumerate(hits)
+            ]
+
+        fallback: list[dict[str, Any]] = []
+        corpus = self.root / "data" / "processed" / "retrieval_corpus.jsonl"
+        if corpus.exists():
+            query_tokens = {token for token in query.lower().split() if token}
+            with corpus.open("r", encoding="utf-8") as handle:
+                for idx, line in enumerate(handle):
+                    if len(fallback) >= 5:
+                        break
+                    text = line.strip()
+                    if not text:
+                        continue
+                    hay = text.lower()
+                    if query_tokens and not any(token in hay for token in query_tokens):
+                        continue
+                    fallback.append(
+                        {
+                            "patient_id": f"retrieval_corpus_{idx}",
+                            "query": query,
+                            "source_path": str(corpus),
+                            "snippet": text[:280],
+                        }
+                    )
+        return fallback
+
+    def evidence_query(self, query: str, top_k: int = 5) -> list[dict[str, str]]:
+        return retrieve_evidence(query=query, top_k=top_k)
+
+    @staticmethod
+    def _candidate_obj(payload: dict) -> Any:
+        from app.common.types import CandidateAction
+
+        return CandidateAction.model_validate(payload)

app/common/config.py

@@ -0,0 +1,57 @@
+"""Configuration loading."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as handle:
+        return yaml.safe_load(handle) or {}
+
+
+def load_config(config_name: str = "base.yaml") -> dict[str, Any]:
+    root = Path(__file__).resolve().parents[2]
+    config_path = root / "configs" / config_name
+    return _read_yaml(config_path)
+
+
+def load_project_env(path: Path | None = None) -> None:
+    """Load simple KEY=VALUE pairs from .env without overriding shell env."""
+
+    root = Path(__file__).resolve().parents[2]
+    env_path = path or root / ".env"
+    if not env_path.exists():
+        return
+    for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if not key or key in os.environ:
+            continue
+        os.environ[key] = value.strip().strip('"').strip("'")
+
+
+def env_bool(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def env_int(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default

app/common/constants.py

@@ -0,0 +1,40 @@
+"""Shared constants for POLYGUARD-RL."""
+
+from __future__ import annotations
+
+REWARD_MIN: float = 0.001
+REWARD_MAX: float = 0.999
+REWARD_PRECISION: int = 3
+
+DEFAULT_SEED: int = 42
+DEFAULT_MAX_STEPS: int = 10
+MAX_REPEATED_ACTIONS: int = 3
+MAX_KEEP_REGIMEN_RATIO: float = 0.6
+MAX_REVIEW_RATIO: float = 0.5
+DEFAULT_STEP_TIMEOUT_SECONDS: float = 2.5
+DEFAULT_EPISODE_TIMEOUT_SECONDS: float = 45.0
+
+DEFAULT_REWARD_WEIGHTS: dict[str, float] = {
+    "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,
+}
+
+REQUIRED_REWARD_KEYS: tuple[str, ...] = tuple(DEFAULT_REWARD_WEIGHTS.keys())
+
+PRIMARY_REWARD_KEYS: tuple[str, ...] = (
+    "safety_legality",
+    "clinical_improvement",
+    "dosing_quality",
+    "process_integrity",
+)

app/common/enums.py

@@ -0,0 +1,61 @@
+"""Enumerations used throughout POLYGUARD-RL."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Difficulty(str, Enum):
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+
+
+class SubEnvironment(str, Enum):
+    DDI = "DDI"
+    BANDIT_MINING = "BANDIT_MINING"
+    REGIMEN_RISK = "REGIMEN_RISK"
+    PRECISION_DOSING = "PRECISION_DOSING"
+    LONGITUDINAL_DEPRESCRIBING = "LONGITUDINAL_DEPRESCRIBING"
+    WEB_SEARCH_MISSING_DATA = "WEB_SEARCH_MISSING_DATA"
+    ALTERNATIVE_SUGGESTION = "ALTERNATIVE_SUGGESTION"
+    NEW_DRUG_DECOMPOSITION = "NEW_DRUG_DECOMPOSITION"
+
+
+class DecisionMode(str, Enum):
+    REGIMEN_OPT = "REGIMEN_OPT"
+    DOSE_OPT = "DOSE_OPT"
+    REVIEW = "REVIEW"
+    ABSTAIN_REVIEW = "ABSTAIN_REVIEW"
+
+
+class ActionType(str, Enum):
+    KEEP_REGIMEN = "KEEP_REGIMEN"
+    STOP_DRUG = "STOP_DRUG"
+    SUBSTITUTE_WITHIN_CLASS = "SUBSTITUTE_WITHIN_CLASS"
+    RECOMMEND_ALTERNATIVE = "RECOMMEND_ALTERNATIVE"
+    REDUCE_DOSE_BUCKET = "REDUCE_DOSE_BUCKET"
+    INCREASE_DOSE_BUCKET = "INCREASE_DOSE_BUCKET"
+    TAPER_INITIATE = "TAPER_INITIATE"
+    TAPER_CONTINUE = "TAPER_CONTINUE"
+    DOSE_HOLD = "DOSE_HOLD"
+    ORDER_MONITORING_AND_WAIT = "ORDER_MONITORING_AND_WAIT"
+    FETCH_EXTERNAL_EVIDENCE = "FETCH_EXTERNAL_EVIDENCE"
+    DECOMPOSE_NEW_DRUG = "DECOMPOSE_NEW_DRUG"
+    REQUEST_SPECIALIST_REVIEW = "REQUEST_SPECIALIST_REVIEW"
+    REQUEST_PHARMACIST_REVIEW = "REQUEST_PHARMACIST_REVIEW"
+
+
+class DoseBucket(str, Enum):
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    HOLD = "HOLD"
+    NA = "NA"
+
+
+class CoordinationMode(str, Enum):
+    SEQUENTIAL = "sequential_pipeline"
+    SUPERVISOR_ROUTED = "supervisor_routed"
+    REPLAN_ON_VETO = "replan_on_veto"
+    LIGHT_DEBATE = "lightweight_debate"

app/common/exceptions.py

@@ -0,0 +1,19 @@
+"""Custom exceptions."""
+
+from __future__ import annotations
+
+
+class PolyGuardError(Exception):
+    """Base exception for project errors."""
+
+
+class InvalidActionError(PolyGuardError):
+    """Raised when an action is malformed or disallowed."""
+
+
+class SafetyVetoError(PolyGuardError):
+    """Raised when safety governance rejects an action."""
+
+
+class ParserError(PolyGuardError):
+    """Raised when structured policy output cannot be parsed."""

app/common/json_utils.py

@@ -0,0 +1,14 @@
+"""Strict JSON helpers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def safe_json_dumps(payload: Any) -> str:
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True, default=str)
+
+
+def safe_json_loads(payload: str) -> Any:
+    return json.loads(payload)

app/common/logging_utils.py

@@ -0,0 +1,17 @@
+"""Logging utilities."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+
+def configure_logging(level: str = "INFO") -> None:
+    logging.basicConfig(
+        level=getattr(logging, level.upper(), logging.INFO),
+        format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+    )
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    return logging.getLogger(name or "polyguard")

app/common/normalization.py

@@ -0,0 +1,24 @@
+"""Normalization and reward range utilities."""
+
+from __future__ import annotations
+
+from app.common.constants import REWARD_MAX, REWARD_MIN, REWARD_PRECISION
+
+
+def clamp_reward(value: float) -> float:
+    """Clamp and quantize reward to [0.001, 0.999] with 3 decimals."""
+    value = min(REWARD_MAX, max(REWARD_MIN, float(value)))
+    return round(value, REWARD_PRECISION)
+
+
+def normalize_unit_interval(value: float, lower: float, upper: float) -> float:
+    if upper <= lower:
+        return 0.5
+    ratio = (value - lower) / (upper - lower)
+    return float(min(1.0, max(0.0, ratio)))
+
+
+def to_reward(value: float, lower: float, upper: float) -> float:
+    raw = normalize_unit_interval(value, lower, upper)
+    scaled = REWARD_MIN + raw * (REWARD_MAX - REWARD_MIN)
+    return clamp_reward(scaled)

app/common/seeding.py

@@ -0,0 +1,17 @@
+"""Deterministic seeding helpers."""
+
+from __future__ import annotations
+
+import os
+import random
+
+import numpy as np
+
+from app.common.constants import DEFAULT_SEED
+
+
+def set_global_seed(seed: int = DEFAULT_SEED) -> int:
+    random.seed(seed)
+    np.random.seed(seed)
+    os.environ["PYTHONHASHSEED"] = str(seed)
+    return seed

app/common/types.py

@@ -0,0 +1,175 @@
+"""Core typed models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.common.enums import ActionType, DecisionMode, Difficulty, DoseBucket, SubEnvironment
+from app.common.normalization import clamp_reward
+
+
+class StrictBase(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Medication(StrictBase):
+    drug: str
+    dose_bucket: DoseBucket = DoseBucket.MEDIUM
+    indication: Optional[str] = None
+    class_name: Optional[str] = None
+    requires_taper: bool = False
+
+
+class LabSummary(StrictBase):
+    egfr: Optional[float] = None
+    ast: Optional[float] = None
+    alt: Optional[float] = None
+    inr: Optional[float] = None
+    glucose: Optional[float] = None
+
+
+class PatientProfile(StrictBase):
+    patient_id: str
+    age: int
+    sex: str
+    comorbidities: list[str] = Field(default_factory=list)
+    medications: list[Medication] = Field(default_factory=list)
+    labs: LabSummary = Field(default_factory=LabSummary)
+    vitals: dict[str, float] = Field(default_factory=dict)
+    specialist_conflicts: list[str] = Field(default_factory=list)
+    prior_ade_history: list[str] = Field(default_factory=list)
+    frailty_score: float = 0.3
+    adherence_estimate: float = 0.8
+    latent_confounders: dict[str, float] = Field(default_factory=dict)
+    monitoring_gaps: list[str] = Field(default_factory=list)
+
+
+class CandidateAction(StrictBase):
+    candidate_id: str
+    mode: DecisionMode
+    action_type: ActionType
+    target_drug: Optional[str] = None
+    replacement_drug: Optional[str] = None
+    dose_bucket: DoseBucket = DoseBucket.NA
+    taper_days: Optional[int] = None
+    monitoring_plan: Optional[str] = None
+    evidence_query: Optional[str] = None
+    new_drug_name: Optional[str] = None
+    candidate_components: list[str] = Field(default_factory=list)
+    estimated_safety_delta: float = 0.0
+    burden_delta: float = 0.0
+    disease_stability_estimate: float = 0.0
+    uncertainty_score: float = 0.5
+    rationale_tags: list[str] = Field(default_factory=list)
+    required_monitoring: list[str] = Field(default_factory=list)
+    legality_precheck: bool = True
+
+
+class PolyGuardAction(StrictBase):
+    mode: DecisionMode
+    action_type: ActionType
+    target_drug: Optional[str] = None
+    replacement_drug: Optional[str] = None
+    dose_bucket: DoseBucket = DoseBucket.NA
+    taper_days: Optional[int] = None
+    monitoring_plan: Optional[str] = None
+    evidence_query: Optional[str] = None
+    new_drug_name: Optional[str] = None
+    candidate_components: list[str] = Field(default_factory=list)
+    candidate_id: str
+    confidence: float
+    rationale_brief: str
+
+    @field_validator("confidence")
+    @classmethod
+    def _valid_confidence(cls, value: float) -> float:
+        return clamp_reward(value)
+
+
+class RewardBreakdown(StrictBase):
+    format_compliance_score: float
+    candidate_alignment_score: float
+    legality_score: float
+    safety_delta_score: float
+    burden_improvement_score: float
+    disease_stability_score: float
+    dosing_quality_score: float
+    abstention_quality_score: float
+    efficiency_score: float
+    process_fidelity_score: float
+    explanation_grounding_score: float
+    anti_cheat_score: float
+    uncertainty_calibration_score: float
+    primary_safety_legality: float = 0.5
+    primary_clinical_improvement: float = 0.5
+    primary_dosing_quality: float = 0.5
+    primary_process_integrity: float = 0.5
+    total_reward: float
+
+
+class SafetyReport(StrictBase):
+    legal: bool
+    violations: list[str] = Field(default_factory=list)
+    severity: str = "none"
+    recommended_fallback: Optional[ActionType] = None
+    uncertainty_notes: list[str] = Field(default_factory=list)
+
+
+class UncertaintyReport(StrictBase):
+    overall_uncertainty: float = 0.5
+    missing_data_flags: list[str] = Field(default_factory=list)
+    abstention_recommended: bool = False
+
+
+class PolyGuardState(StrictBase):
+    episode_id: str
+    seed: int
+    scenario_id: Optional[str] = None
+    difficulty: Difficulty
+    sub_environment: SubEnvironment = SubEnvironment.REGIMEN_RISK
+    step_count: int
+    max_steps: int
+    patient: PatientProfile
+    active_mode: DecisionMode = DecisionMode.REGIMEN_OPT
+    cumulative_reward: float = 0.0
+    unresolved_conflicts: list[str] = Field(default_factory=list)
+    risk_summary: dict[str, float] = Field(default_factory=dict)
+    burden_score: float = 0.5
+    precision_dosing_flags: list[str] = Field(default_factory=list)
+    action_history: list[dict[str, Any]] = Field(default_factory=list)
+    done: bool = False
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class PolyGuardObservation(StrictBase):
+    patient_summary: dict[str, Any]
+    medication_table: list[dict[str, Any]]
+    comorbidity_summary: list[str]
+    organ_function_summary: dict[str, Any]
+    labs_vitals_summary: dict[str, Any]
+    graph_safety_summary: dict[str, Any]
+    burden_score_summary: dict[str, Any]
+    precision_dosing_flags: list[str]
+    unresolved_conflicts: list[str]
+    candidate_action_set: list[CandidateAction]
+    step_budget_remaining: int
+    action_history: list[dict[str, Any]]
+    warning_summary: list[str]
+    abstention_indicators: dict[str, Any]
+    sub_environment: SubEnvironment
+    deterministic_contract: dict[str, Any] = Field(default_factory=dict)
+
+
+class StepTrace(StrictBase):
+    step: int
+    observation_snapshot: PolyGuardObservation
+    selected_action: Optional[PolyGuardAction] = None
+    critic_output: dict[str, Any] = Field(default_factory=dict)
+    reward_components: dict[str, float] = Field(default_factory=dict)
+    transition_delta: dict[str, Any] = Field(default_factory=dict)
+    uncertainty_report: UncertaintyReport = Field(default_factory=UncertaintyReport)
+    failure_reasons: list[str] = Field(default_factory=list)
+    timeout: bool = False

app/dataops/__init__.py

@@ -0,0 +1,5 @@
+"""Data operations package."""
+
+from app.dataops.source_manager import SourceManager
+
+__all__ = ["SourceManager"]

app/dataops/ddi_api.py

@@ -0,0 +1,65 @@
+"""DDI API ingestion helpers with offline-first caching."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import requests
+
+
+DEFAULT_DDI_API_URL = "https://api.fda.gov/drug/label.json"
+
+
+def fetch_ddi_api_records(
+    drugs: list[str],
+    timeout: int = 20,
+    api_url: str = DEFAULT_DDI_API_URL,
+) -> list[dict[str, Any]]:
+    records: list[dict[str, Any]] = []
+    for drug in drugs:
+        try:
+            response = requests.get(
+                api_url,
+                params={"search": f"openfda.generic_name:{drug}", "limit": 1},
+                timeout=timeout,
+            )
+            response.raise_for_status()
+            payload = response.json()
+            records.append(
+                {
+                    "drug": drug,
+                    "source": api_url,
+                    "status": "ok",
+                    "payload": payload,
+                }
+            )
+        except Exception as exc:  # noqa: BLE001
+            records.append(
+                {
+                    "drug": drug,
+                    "source": api_url,
+                    "status": "error",
+                    "error": str(exc),
+                }
+            )
+    return records
+
+
+def load_cached_ddi(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(payload, list):
+            return payload
+        return []
+    except Exception:
+        return []
+
+
+def cache_ddi_records(path: Path, records: list[dict[str, Any]]) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(records, ensure_ascii=True, indent=2), encoding="utf-8")
+    return path

app/dataops/normalizer.py

@@ -0,0 +1,13 @@
+"""Entity normalizer."""
+
+from __future__ import annotations
+
+from app.knowledge.drug_catalog import canonicalize_drug_name
+
+
+def normalize_drug_entities(items: list[str]) -> list[str]:
+    return sorted({canonicalize_drug_name(item) for item in items})
+
+
+def normalize_component_entities(items: list[str]) -> list[str]:
+    return sorted({canonicalize_drug_name(item).replace("-", "_") for item in items if item})

app/dataops/package_loader.py

@@ -0,0 +1,19 @@
+"""Package/local artifact loading."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_artifact(path: Path) -> Any:
+    if path.suffix.lower() in {".json"}:
+        return json.loads(path.read_text(encoding="utf-8"))
+    if path.suffix.lower() in {".yaml", ".yml"}:
+        return yaml.safe_load(path.read_text(encoding="utf-8"))
+    if path.suffix.lower() in {".txt", ".md"}:
+        return path.read_text(encoding="utf-8")
+    return path.read_bytes()

app/dataops/parser.py

@@ -0,0 +1,26 @@
+"""Raw text parser for knowledge ingestion."""
+
+from __future__ import annotations
+
+import re
+
+
+def extract_drug_mentions(text: str) -> list[str]:
+    tokens = re.findall(r"[a-zA-Z_-]{4,}", text.lower())
+    return sorted(set(tokens))
+
+
+def extract_components(text: str) -> list[str]:
+    # Supports "active ingredient(s): ..." and similar label patterns.
+    lines = [line.strip().lower() for line in text.splitlines() if line.strip()]
+    components: list[str] = []
+    for line in lines:
+        if "ingredient" in line or "component" in line or "contains" in line:
+            parts = re.split(r":|\\.|;", line, maxsplit=1)
+            if len(parts) > 1:
+                rhs = parts[1]
+                for item in re.split(r",|/| and ", rhs):
+                    token = re.sub(r"[^a-z0-9_ -]", "", item).strip().replace(" ", "_")
+                    if 3 <= len(token) <= 40:
+                        components.append(token)
+    return sorted(set(components))

app/dataops/provenance.py

@@ -0,0 +1,31 @@
+"""Provenance tracking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(slots=True)
+class ProvenanceRecord:
+    source: str
+    source_type: str
+    fetched_at: str
+    transform: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "source": self.source,
+            "source_type": self.source_type,
+            "fetched_at": self.fetched_at,
+            "transform": self.transform,
+        }
+
+
+def make_provenance(source: str, source_type: str, transform: str) -> ProvenanceRecord:
+    return ProvenanceRecord(
+        source=source,
+        source_type=source_type,
+        fetched_at=datetime.utcnow().isoformat(),
+        transform=transform,
+    )

app/dataops/scraper.py

@@ -0,0 +1,9 @@
+"""Controlled scraper facade."""
+
+from __future__ import annotations
+
+from app.dataops.web_agent import fetch_url
+
+
+def scrape_allowed_page(url: str, allow_domains: list[str]) -> str:
+    return fetch_url(url, allowed_domains=allow_domains)

app/dataops/source_manager.py

@@ -0,0 +1,111 @@
+"""Source management for offline-first ingestion."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from app.dataops.web_agent import fetch_url
+from app.dataops.parser import extract_components, extract_drug_mentions
+from app.dataops.normalizer import normalize_component_entities, normalize_drug_entities
+from app.dataops.provenance import make_provenance
+
+
+class SourceManager:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.raw = root / "data" / "raw"
+        self.cache = root / "data" / "cache"
+        self.cache.mkdir(parents=True, exist_ok=True)
+
+    def local_sources(self) -> list[Path]:
+        return [p for p in self.raw.rglob("*") if p.is_file()]
+
+    @staticmethod
+    def checksum_text(text: str) -> str:
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def cache_text(self, namespace: str, key: str, text: str) -> Path:
+        ns_dir = self.cache / namespace
+        ns_dir.mkdir(parents=True, exist_ok=True)
+        checksum = self.checksum_text(text)
+        target = ns_dir / f"{key}_{checksum[:12]}.txt"
+        target.write_text(text, encoding="utf-8")
+        meta = {
+            "key": key,
+            "checksum": checksum,
+            "path": str(target),
+        }
+        (ns_dir / f"{key}.meta.json").write_text(json.dumps(meta, ensure_ascii=True, indent=2), encoding="utf-8")
+        return target
+
+    def read_cached(self, namespace: str, key: str) -> str | None:
+        meta_path = self.cache / namespace / f"{key}.meta.json"
+        if not meta_path.exists():
+            return None
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        target = Path(meta["path"])
+        if target.exists():
+            return target.read_text(encoding="utf-8")
+        return None
+
+    def fetch_with_cache(
+        self,
+        url: str,
+        allow_domains: list[str],
+        namespace: str = "web",
+        offline_first: bool = True,
+    ) -> dict[str, Any]:
+        key = url.replace("https://", "").replace("http://", "").replace("/", "_")
+        if offline_first:
+            cached = self.read_cached(namespace=namespace, key=key)
+            if cached is not None:
+                provenance = make_provenance(source=url, source_type="cache", transform="read_cached")
+                return {"text": cached, "provenance": provenance.__dict__, "from_cache": True}
+        text = fetch_url(url, allowed_domains=allow_domains)
+        self.cache_text(namespace=namespace, key=key, text=text)
+        provenance = make_provenance(source=url, source_type="web", transform="fetch_with_cache")
+        return {"text": text, "provenance": provenance.__dict__, "from_cache": False}
+
+
+class DataAcquisitionAgent:
+    def __init__(self, root: Path, allow_domains: list[str]) -> None:
+        self.manager = SourceManager(root=root)
+        self.allow_domains = allow_domains
+
+    def acquire_local_knowledge(self) -> list[dict[str, Any]]:
+        records: list[dict[str, Any]] = []
+        for source in self.manager.local_sources():
+            text = source.read_text(encoding="utf-8", errors="ignore")
+            mentions = normalize_drug_entities(extract_drug_mentions(text))
+            components = normalize_component_entities(extract_components(text))
+            provenance = make_provenance(source=str(source), source_type="local_file", transform="parse_local").to_dict()
+            records.append(
+                {
+                    "source": str(source),
+                    "mentions": mentions,
+                    "components": components,
+                    "provenance": provenance,
+                }
+            )
+        return records
+
+    def acquire_web_knowledge(self, url: str, offline_first: bool = True) -> dict[str, Any]:
+        blob = self.manager.fetch_with_cache(
+            url=url,
+            allow_domains=self.allow_domains,
+            namespace="drug_labels",
+            offline_first=offline_first,
+        )
+        text = blob["text"]
+        mentions = normalize_drug_entities(extract_drug_mentions(text))
+        components = normalize_component_entities(extract_components(text))
+        return {
+            "url": url,
+            "mentions": mentions,
+            "components": components,
+            "provenance": blob["provenance"],
+            "from_cache": blob["from_cache"],
+        }