Deploy PolyGuard OpenEnv Space

.env.example

@@ -0,0 +1,13 @@
+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_OLLAMA_MODEL=qwen2.5:3b-instruct
+POLYGUARD_FRONTIER_MODEL=Qwen/Qwen2.5-7B-Instruct
+POLYGUARD_ALLOW_WEB_FETCH=false
+POLYGUARD_REWARD_MIN=0.001
+POLYGUARD_REWARD_MAX=0.999

.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+.env
+node_modules/
+dist/
+build/
+*.log
+outputs/
+checkpoints/
+artifacts/
+data/cache/*
+data/processed/*
+data/synthetic/*
+data/retrieval_index/*
+!data/**/.gitkeep
+app/ui/frontend/.vite/

Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8100 8200
+
+CMD ["python", "-m", "server.app", "--host", "0.0.0.0", "--port", "8100"]

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

README.md

@@ -1,10 +1,246 @@
 ---
-title: Polyguard Openenv
-emoji: 📉
-colorFrom: red
-colorTo: purple
+title: PolyGuard OpenEnv
+colorFrom: blue
+colorTo: green
 sdk: docker
+app_port: 8100
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# POLYGUARD-OPENENV
+
+PolyGuard is an OpenEnv-compatible reinforcement-learning environment for **polypharmacy safety, medication optimization, deprescribing, and precision dosing**. The project turns medication decision making into a stateful environment where an LLM agent observes a patient/regimen state, chooses constrained clinical actions, receives verifier-backed reward, and improves through TRL/GRPO-style post-training.
+
+> Clinical safety note: this is a research environment and demo system for RL environment design. It is not a medical device and must not be used for patient care.
+
+## 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/Vishwa-docs/polyguard-openenv](https://huggingface.co/spaces/Vishwa-docs/polyguard-openenv) *(deployment target; verify before final submission)*
+- Colab Notebook URL: [https://colab.research.google.com/github/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK/blob/master/polyguard-rl/notebooks/09_training_loop.ipynb](https://colab.research.google.com/github/Vishwa-docs/Meta_Pytorch_OpenEnv_Scaler_VK/blob/master/polyguard-rl/notebooks/09_training_loop.ipynb)
+- YouTube Video URL: not used for this submission; the Hugging Face blog URL below is the selected story artifact.
+- Hugging Face Blog URL: [https://huggingface.co/blog/Vishwa-docs/polyguard-openenv](https://huggingface.co/blog/Vishwa-docs/polyguard-openenv) *(story target; publish before final submission)*
+
+## Current Readiness
+
+Verified locally:
+
+- `uv run pytest`: 36 tests passed during the audit pass.
+- `uv run openenv validate .`: local OpenEnv packaging passed.
+- `bash scripts/bootstrap_openenv.sh --runtime-check`: runtime OpenEnv HTTP contract passed when localhost access was allowed.
+- `npm run build` in `app/ui/frontend`: production UI build passed.
+
+Still required for final judge-ready submission:
+
+- Authenticate Hugging Face with `./.venv/bin/hf auth login`.
+- Deploy and verify the HF Space.
+- Run real TRL/Unsloth SFT and GRPO on GPU/Colab so reports no longer show fallback paths.
+- Replace `docs/results/hf_space_verification.json` with a successful verification payload.
+- Regenerate final plots and reports with `improvement_report.improved == true`.
+- Run strict readiness: `POLYGUARD_ENFORCE_SUBMISSION_LINKS=true ./.venv/bin/python scripts/acceptance_gate.py`.
+
+## Problem Statement
+
+Polypharmacy decisions are long-horizon, partially observable, and safety-critical. A useful LLM agent must do more than produce a plausible recommendation: it should identify drug-drug interaction risk, reason over comorbidities and labs, choose safe substitutions or deprescribing sequences, request review when uncertain, and expose why it acted.
+
+PolyGuard targets the OpenEnv **World Modeling / Professional Tasks** theme, with multi-agent and self-improvement elements. It asks whether environment-backed feedback can make a model better at safe medication action selection than prompt-only or rule-only baselines.
+
+## Environment
+
+The environment is implemented by `PolyGuardEnv` and exposed through FastAPI/OpenEnv-compatible endpoints:
+
+- `POST /reset`
+- `POST /step`
+- `GET /state`
+- `GET /metadata`
+- `GET /schema`
+- `POST /mcp`
+- `GET /health`
+- Backward-compatible aliases under `/env/*` plus `/ws`
+
+OpenEnv packaging lives at repo root:
+
+- `openenv.yaml`
+- `__init__.py`
+- `client.py`
+- `models.py`
+- `server/app.py`
+
+Each episode samples a patient/regimen scenario and a sub-environment:
+
+- `DDI`
+- `BANDIT_MINING`
+- `REGIMEN_RISK`
+- `PRECISION_DOSING`
+- `LONGITUDINAL_DEPRESCRIBING`
+- `WEB_SEARCH_MISSING_DATA`
+- `ALTERNATIVE_SUGGESTION`
+- `NEW_DRUG_DECOMPOSITION`
+
+Difficulty tracks are available as easy, medium, and hard scenario sets.
+
+## Agent Capabilities
+
+The agent stack is deliberately decomposed so reward, safety, and explanation can be inspected:
+
+- Medication reconciliation
+- Evidence retrieval and missing-data recovery
+- Graph safety analysis for DDI and side effects
+- Dosing guardrails
+- Candidate generation
+- Supervisor routing between regimen, dose, and review modes
+- Planner policy selection
+- Critic safety veto
+- Explanation generation
+- Contextual bandit ranking for policy-stack ablations
+
+## Tasks
+
+PolyGuard evaluates these action-selection tasks:
+
+- Find bad drug combinations and reduce DDI/polypharmacy side-effect risk.
+- Recommend safe adds, substitutions, and alternatives.
+- Optimize regimens under uncertainty.
+- Produce taper/deprescribing sequences over time.
+- Choose precision dosing actions when organ function or dose sensitivity matters.
+- Fetch evidence when critical data is missing.
+- Decompose a new drug into components for first-pass safety reasoning.
+
+## Reward Model / Evaluation Logic
+
+Rewards are verifier-backed and clamped to `[0.001, 0.999]`. The environment exposes 13 detailed reward columns and 4 primary channels:
+
+- `safety_legality`
+- `clinical_improvement`
+- `dosing_quality`
+- `process_integrity`
+
+Reward logic combines:
+
+- Legal action checks
+- Safety delta and burden improvement
+- Dosing quality
+- Abstention quality under uncertainty
+- Format compliance
+- Process fidelity
+- Explanation grounding
+- Anti-cheat and timeout penalties
+
+Anti-hacking checks block repeated action loops, review abuse, keep-regimen abuse, candidate ID mismatches, parser exploit patterns, and unsafe no-op behavior on known holdout DDIs.
+
+## Training And Post-Training Strategy
+
+The intended pipeline is:
+
+1. Build data assets from local knowledge, synthetic patients, scenario rollouts, optional HF instruction data, optional DDI API augmentation, and optional web fallback.
+2. Run SFT with TRL and optional Unsloth/QLoRA acceleration to teach action-selection format.
+3. Run GRPO with environment-backed reward verification.
+4. Track per-component reward columns and sampled generations.
+5. Run policy-stack ablations against baselines.
+6. Merge/export adapters safely.
+7. Validate post-save inference from the exported artifact.
+8. Deploy the OpenEnv environment to Hugging Face Spaces.
+
+Core commands:
+
+```bash
+cd polyguard-rl
+bash scripts/bootstrap_venv.sh
+.venv/bin/python scripts/bootstrap_data.py
+.venv/bin/python scripts/build_training_corpus.py --profile small --with-local --with-synthetic --with-hf
+.venv/bin/python scripts/train_sft_trl.py --model-id Qwen/Qwen2.5-1.5B-Instruct --epochs 1 --max-steps 20 --use-unsloth
+.venv/bin/python scripts/train_grpo_trl.py --model-id Qwen/Qwen2.5-1.5B-Instruct --max-steps 20 --num-generations 2 --use-unsloth
+.venv/bin/python scripts/merge_adapters_safe.py --adapter-dir checkpoints/sft_adapter --output-dir checkpoints/merged
+.venv/bin/python scripts/test_inference_postsave.py --samples 3
+.venv/bin/python scripts/evaluate_all.py
+```
+
+## Results
+
+Tracked smoke/evaluation artifacts are mirrored in `docs/results/` because `outputs/` and `checkpoints/` are intentionally ignored.
+
+![Average reward](docs/results/avg_reward.png)
+
+![Policy stack average reward](docs/results/policy_stack_avg_reward.png)
+
+Current smoke reports show the environment, evaluation, and plotting paths are wired, but final training is not yet judge-ready:
+
+- `docs/results/sft_trl_run.json` currently records a fallback backend.
+- `docs/results/grpo_trl_run.json` currently records an environment-reward fallback path.
+- `docs/results/postsave_inference.json` currently uses fallback inference.
+- `docs/results/improvement_report.json` currently records no positive improvement.
+- `docs/results/hf_space_verification.json` is blocked until HF auth/deployment succeeds.
+
+Final submission should replace these with real GPU/Colab TRL/Unsloth artifacts.
+
+## Dataset Gather
+
+Implemented data generation and packaging covers:
+
+- Normalized drug vocabulary and class tables
+- Interaction graph edges
+- Burden, taper, renal, hepatic, duplicate-therapy, and substitution rules
+- Synthetic patients
+- Easy/medium/hard scenario files
+- Retrieval corpus and local evidence index
+- Unified SFT and GRPO prompt corpora
+
+The current local corpus summary is in `data/processed/training_corpus_summary.json` when generated.
+
+## Deployment
+
+Use the repository-local HF CLI entrypoint. The global `hf` command on this machine is known to be incompatible with its installed Typer version.
+
+```bash
+./.venv/bin/hf auth login
+./.venv/bin/hf auth whoami
+export HF_SPACE_REPO_ID="Vishwa-docs/polyguard-openenv"
+bash scripts/deploy_space.sh --repo-id "$HF_SPACE_REPO_ID"
+./.venv/bin/hf spaces info "$HF_SPACE_REPO_ID"
+openenv validate --url "https://Vishwa-docs-polyguard-openenv.hf.space"
+```
+
+After deployment, save the successful Space info plus OpenEnv validation payload into `docs/results/hf_space_verification.json`.
+
+## Strict Submission Gate
+
+Non-strict local readiness:
+
+```bash
+.venv/bin/python scripts/acceptance_gate.py
+```
+
+Final submission readiness:
+
+```bash
+export POLYGUARD_ENFORCE_SUBMISSION_LINKS=true
+.venv/bin/python scripts/acceptance_gate.py
+```
+
+Strict mode fails unless README links are real, tracked plots exist, HF Space verification passed, SFT/GRPO used real TRL/Unsloth paths, post-save inference uses the exported artifact, and measured improvement is positive.
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Environment Design](docs/environment_design.md)
+- [Reward Design](docs/reward_design.md)
+- [Training](docs/training.md)
+- [Evaluation](docs/evaluation.md)
+- [Deployment](docs/deployment.md)
+- [Safety](docs/safety.md)
+- [Agents](docs/agents.md)
+- [Datasets](docs/datasets.md)
+- [Math](docs/math.md)
+- [Submission Checklist](docs/submission_checklist.md)
+
+## Future Work
+
+- Medicine image/barcode ingestion for regimen capture
+- Larger model GRPO sweeps
+- Stronger real-world drug-label ingestion and calibration
+- More clinician-facing explanation studies
+- Published HF blog or short video walkthrough
+
+## License
+
+MIT

__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
+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, ...] = ("transformers",),
+    ) -> 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,
+        )
+        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,34 @@
+"""API application entrypoint."""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.api.routes import router
+
+app = FastAPI(title="POLYGUARD-RL API", version="0.1.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://127.0.0.1:5173",
+        "http://localhost:5173",
+    ],
+    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,134 @@
+"""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.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,186 @@
+"""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.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.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()
+        return legal[0] if legal else {}
+
+    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,39 @@
+"""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 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"],
+        }

app/dataops/synthetic_mix.py

@@ -0,0 +1,9 @@
+"""Synthetic and mock data blending."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def merge_sources(local_items: list[dict[str, Any]], generated_items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return local_items + generated_items

app/dataops/web_agent.py

@@ -0,0 +1,20 @@
+"""Allow-listed web retrieval."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import requests
+
+
+def fetch_url(url: str, allowed_domains: list[str]) -> str:
+    host = urlparse(url).netloc.lower()
+    if not any(host.endswith(domain) for domain in allowed_domains):
+        raise ValueError(f"Domain not allow-listed: {host}")
+    try:
+        response = requests.get(url, timeout=20)
+        response.raise_for_status()
+        return response.text
+    except Exception as exc:  # noqa: BLE001
+        # Explicit failure message makes offline-first behavior easier to reason about upstream.
+        raise RuntimeError(f"web_fetch_failed:{host}:{exc}") from exc

app/dataops/web_fallback.py

@@ -0,0 +1,59 @@
+"""Optional web fallback ingestion via Scrapling and Playwright."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import requests
+
+
+def _allowed(url: str, allow_domains: list[str]) -> bool:
+    host = urlparse(url).netloc.lower()
+    return any(host.endswith(domain) for domain in allow_domains)
+
+
+def _scrape_with_scrapling(url: str) -> str:
+    # Scrapling API compatibility may vary by version, so this path is best-effort.
+    from scrapling import Fetcher  # type: ignore
+
+    fetcher = Fetcher()
+    page = fetcher.get(url)
+    return getattr(page, "text", "") or ""
+
+
+def _scrape_with_playwright(url: str) -> str:
+    from playwright.sync_api import sync_playwright  # type: ignore
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        page = browser.new_page()
+        page.goto(url, timeout=30_000)
+        content = page.content()
+        browser.close()
+        return content
+
+
+def scrape_with_fallback(url: str, allow_domains: list[str]) -> dict[str, str]:
+    if not _allowed(url, allow_domains):
+        return {"status": "blocked", "url": url, "backend": "allowlist"}
+
+    try:
+        text = _scrape_with_scrapling(url)
+        if text:
+            return {"status": "ok", "url": url, "backend": "scrapling", "text": text}
+    except Exception:
+        pass
+
+    try:
+        text = _scrape_with_playwright(url)
+        if text:
+            return {"status": "ok", "url": url, "backend": "playwright", "text": text}
+    except Exception:
+        pass
+
+    try:
+        response = requests.get(url, timeout=20)
+        response.raise_for_status()
+        return {"status": "ok", "url": url, "backend": "requests", "text": response.text}
+    except Exception as exc:  # noqa: BLE001
+        return {"status": "error", "url": url, "backend": "none", "error": str(exc)}

app/env/__init__.py

@@ -0,0 +1,27 @@
+"""Environment package."""
+
+__all__ = ["PolyGuardEnv", "EnvironmentA", "EnvironmentB", "EnvironmentC", "EnvironmentD"]
+
+
+def __getattr__(name: str):
+    if name == "PolyGuardEnv":
+        from app.env.env_core import PolyGuardEnv
+
+        return PolyGuardEnv
+    if name == "EnvironmentA":
+        from app.env.environment_a import EnvironmentA
+
+        return EnvironmentA
+    if name == "EnvironmentB":
+        from app.env.environment_b import EnvironmentB
+
+        return EnvironmentB
+    if name == "EnvironmentC":
+        from app.env.environment_c import EnvironmentC
+
+        return EnvironmentC
+    if name == "EnvironmentD":
+        from app.env.environment_d import EnvironmentD
+
+        return EnvironmentD
+    raise AttributeError(name)

app/env/actions.py

@@ -0,0 +1,7 @@
+"""Environment action helpers."""
+
+from __future__ import annotations
+
+from app.common.types import PolyGuardAction
+
+__all__ = ["PolyGuardAction"]