added the AI layer for explanation

backend/.env.example

@@ -4,5 +4,13 @@ MODEL_MAX_LENGTH=512
 MODEL_NAME=DNABERT-2 ClinVar 20k
 DEVICE=auto
 
+# Optional OpenAI explanation layer.
+# Keep USE_OPENAI_EXPLANATION=false for the local rule-based explanation.
+# To enable it, copy this file to backend/.env and paste your real key there.
+USE_OPENAI_EXPLANATION=false
+OPENAI_API_KEY=
+OPENAI_EXPLANATION_MODEL=gpt-4.1-mini
+OPENAI_EXPLANATION_TIMEOUT=12
+
 # Comma-separated origins for browser clients
 ALLOWED_ORIGINS=http://localhost:3000

backend/README.md

@@ -4,6 +4,9 @@ FastAPI backend for the Variant Risk Explainer research demo.
 
 The backend loads a fine-tuned DNABERT-2 sequence-classification model once at
 startup and exposes `POST /analyze` for DNA sequence risk prediction.
+The response also includes an explanation generated from the model
+probabilities, selected threshold, and prediction label. By default this is
+rule-based. You can optionally enable an OpenAI-powered explanation paragraph.
 
 This is for research/demo use only. It is not a clinical diagnostic system and
 must not be used for medical decisions.
@@ -48,6 +51,23 @@ DEVICE=auto
 
 `DEVICE=auto` selects CUDA, then MPS, then CPU.
 
+## Optional OpenAI Explanation
+
+Do not paste your OpenAI API key into source code or `.env.example`.
+
+Paste it only into your local `backend/.env` file:
+
+```bash
+USE_OPENAI_EXPLANATION=true
+OPENAI_API_KEY=sk-your-real-key-here
+OPENAI_EXPLANATION_MODEL=gpt-4.1-mini
+OPENAI_EXPLANATION_TIMEOUT=12
+```
+
+Then restart the backend. If the OpenAI key is missing, the package is not
+installed, or the API call fails, the backend automatically falls back to the
+local rule-based explanation.
+
 ## Run
 
 From `backend/`:
@@ -110,6 +130,21 @@ print(response.json())
 - `pathogenic_probability`: class 1 probability
 - `threshold`: decision threshold, currently `0.16`
 - `sequence_length_used`: sequence length after optional center crop
+- `explanation`: plain-language explanation of the model output
+- `confidence_level`: rough confidence category based on model probability
+- `recommendation`: safe research/demo recommendation
+- `limitations`: important limitations to show users
+
+## Explanation Layer
+
+The default explanation is generated by local backend rules. When
+`USE_OPENAI_EXPLANATION=true`, the backend asks OpenAI to rewrite only the
+explanation paragraph in beginner-friendly language. The prediction,
+probabilities, threshold, confidence level, recommendation, and limitations stay
+controlled by backend logic.
+
+The wording is intentionally cautious because it is derived only from the model
+output, not from clinical review.
 
 ## Safety Notice
 

backend/app/core/config.py

@@ -18,6 +18,13 @@ def _default_model_dir() -> str:
     return str(_repo_root() / "training" / "training_model_files")
 
 
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
 @dataclass(frozen=True)
 class Settings:
     app_name: str = "variant-risk-explainer"
@@ -28,6 +35,12 @@ class Settings:
     model_name: str = os.getenv("MODEL_NAME", "DNABERT-2 ClinVar 20k").strip() or "DNABERT-2 ClinVar 20k"
     device: str = os.getenv("DEVICE", "auto").strip().lower() or "auto"
     max_sequence_context_length: int = int(os.getenv("MAX_SEQUENCE_CONTEXT_LENGTH", "2000"))
+    use_openai_explanation: bool = _env_bool("USE_OPENAI_EXPLANATION", False)
+    openai_api_key: str = os.getenv("OPENAI_API_KEY", "").strip()
+    openai_explanation_model: str = (
+        os.getenv("OPENAI_EXPLANATION_MODEL", "gpt-4.1-mini").strip() or "gpt-4.1-mini"
+    )
+    openai_explanation_timeout: float = float(os.getenv("OPENAI_EXPLANATION_TIMEOUT", "12"))
     allowed_origins: tuple[str, ...] = tuple(
         origin.strip()
         for origin in os.getenv("ALLOWED_ORIGINS", "http://localhost:3000").split(",")
@@ -57,6 +70,8 @@ class Settings:
             raise ValueError("MODEL_MAX_LENGTH must be positive")
         if self.device not in {"auto", "cuda", "mps", "cpu"}:
             raise ValueError("DEVICE must be one of: auto, cuda, mps, cpu")
+        if self.openai_explanation_timeout <= 0:
+            raise ValueError("OPENAI_EXPLANATION_TIMEOUT must be positive")
         return self
 
 

backend/app/main.py

@@ -5,6 +5,7 @@ from fastapi.middleware.cors import CORSMiddleware
 
 from app.core.config import get_settings
 from app.schemas import AnalyzeRequest, AnalyzeResponse, HealthResponse
+from app.services.explanation_service import generate_explanation
 from app.services.model_service import ModelService
 
 
@@ -59,6 +60,22 @@ def analyze(request: AnalyzeRequest) -> AnalyzeResponse:
     except Exception as exc:  # pragma: no cover - defensive boundary for inference failures.
         raise HTTPException(status_code=500, detail=f"Prediction failed: {type(exc).__name__}: {exc}") from exc
 
+    explanation = generate_explanation(
+        prediction_class=prediction.prediction_class,
+        prediction_label=prediction.prediction_label,
+        risk_level=prediction.risk_level,
+        benign_probability=prediction.benign_probability,
+        pathogenic_probability=prediction.pathogenic_probability,
+        threshold=prediction.threshold,
+        variant_name=request.variant_name,
+        gene=request.gene,
+        sequence_length_used=prediction.sequence_length_used,
+        use_openai=settings.use_openai_explanation,
+        openai_api_key=settings.openai_api_key,
+        openai_model=settings.openai_explanation_model,
+        openai_timeout=settings.openai_explanation_timeout,
+    )
+
     return AnalyzeResponse(
         variant_name=request.variant_name,
         gene=request.gene,
@@ -70,5 +87,9 @@ def analyze(request: AnalyzeRequest) -> AnalyzeResponse:
         threshold=prediction.threshold,
         model_name=prediction.model_name,
         sequence_length_used=prediction.sequence_length_used,
+        explanation=explanation["explanation"],
+        confidence_level=explanation["confidence_level"],
+        recommendation=explanation["recommendation"],
+        limitations=explanation["limitations"],
         disclaimer=prediction.disclaimer,
     )

backend/app/schemas.py

@@ -42,6 +42,10 @@ class AnalyzeResponse(BaseModel):
     threshold: float = Field(..., ge=0.0, le=1.0)
     model_name: str
     sequence_length_used: int
+    explanation: str
+    confidence_level: str
+    recommendation: str
+    limitations: list[str]
     disclaimer: str = DISCLAIMER
 
 

backend/app/services/explanation_service.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import json
+import re
+
+
+LIMITATIONS = [
+    "The model uses DNA sequence patterns and does not replace clinical interpretation.",
+    "The model performance is limited, with test AUC around 0.5928.",
+    "The prediction does not include full clinical evidence, family history, population frequency, or functional studies.",
+    "The result should not be used for diagnosis or treatment decisions.",
+]
+
+RECOMMENDATION = (
+    "This result is for research/demo use only. For any real genetic or medical decision, "
+    "consult a qualified clinical genetics professional and use validated clinical databases/testing."
+)
+
+
+OPENAI_SYSTEM_INSTRUCTIONS = """
+You explain a research-only DNABERT-2 variant risk demo to non-expert users.
+Rules:
+- Do not make clinical claims.
+- Do not say a variant causes disease.
+- Use cautious wording like "the model estimated" and "this may indicate".
+- State that the result is not for diagnosis.
+- Use only the model output values provided in the prompt.
+- Keep the response to one short paragraph.
+- Return JSON only with this shape: {"explanation": "..."}
+""".strip()
+
+
+def _confidence_level(prediction_class: int, benign_probability: float, pathogenic_probability: float, threshold: float) -> str:
+    if prediction_class == 1:
+        if pathogenic_probability >= 0.80:
+            return "High model confidence"
+        if pathogenic_probability >= 0.60:
+            return "Moderate model confidence"
+        if pathogenic_probability >= threshold:
+            return "Low model confidence"
+        return "Low model confidence"
+
+    if benign_probability >= 0.80:
+        return "High model confidence"
+    if benign_probability >= 0.60:
+        return "Moderate model confidence"
+    return "Low model confidence"
+
+
+def _context_text(variant_name: str | None, gene: str | None, sequence_length_used: int | None) -> str:
+    details: list[str] = []
+    if variant_name:
+        details.append(f"variant {variant_name}")
+    if gene:
+        details.append(f"gene {gene}")
+    if sequence_length_used is not None:
+        details.append(f"{sequence_length_used} bases used by the model")
+
+    if not details:
+        return ""
+
+    return " Context: " + "; ".join(details) + "."
+
+
+def _generate_rule_based_explanation(
+    prediction_class: int,
+    prediction_label: str,
+    risk_level: str,
+    benign_probability: float,
+    pathogenic_probability: float,
+    threshold: float,
+    variant_name: str | None = None,
+    gene: str | None = None,
+    sequence_length_used: int | None = None,
+) -> dict:
+    pathogenic_percent = pathogenic_probability * 100.0
+    confidence_level = _confidence_level(
+        prediction_class=prediction_class,
+        benign_probability=benign_probability,
+        pathogenic_probability=pathogenic_probability,
+        threshold=threshold,
+    )
+    context = _context_text(variant_name, gene, sequence_length_used)
+
+    if prediction_class == 1:
+        explanation = (
+            "The DNABERT-2 model estimated this sequence as more similar to pathogenic or likely pathogenic "
+            f"variants in the training data. The pathogenic probability is {pathogenic_percent:.1f}%. "
+            f"Because this is above the selected threshold of {threshold:.2f}, the model labels it as "
+            f"{prediction_label} with an {risk_level.lower()} research-demo risk level."
+            f"{context}"
+        )
+    else:
+        explanation = (
+            "The DNABERT-2 model estimated this sequence as more similar to benign or likely benign "
+            f"variants in the training data. The pathogenic probability is {pathogenic_percent:.1f}%, "
+            f"which is below the selected threshold of {threshold:.2f}. The model labels it as "
+            f"{prediction_label} with a {risk_level.lower()} research-demo risk level."
+            f"{context}"
+        )
+
+    return {
+        "explanation": explanation,
+        "confidence_level": confidence_level,
+        "recommendation": RECOMMENDATION,
+        "limitations": LIMITATIONS,
+    }
+
+
+def _extract_json_object(text: str) -> dict:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+        if not match:
+            raise
+        return json.loads(match.group(0))
+
+
+def _generate_openai_explanation(
+    fallback: dict,
+    prediction_class: int,
+    prediction_label: str,
+    risk_level: str,
+    benign_probability: float,
+    pathogenic_probability: float,
+    threshold: float,
+    openai_api_key: str,
+    openai_model: str,
+    openai_timeout: float,
+    variant_name: str | None,
+    gene: str | None,
+    sequence_length_used: int | None,
+) -> dict:
+    try:
+        from openai import OpenAI
+    except ImportError:
+        print("OpenAI package is not installed. Using rule-based explanation.")
+        return fallback
+
+    context = {
+        "variant_name": variant_name,
+        "gene": gene,
+        "prediction_class": prediction_class,
+        "prediction_label": prediction_label,
+        "risk_level": risk_level,
+        "benign_probability": round(benign_probability, 6),
+        "pathogenic_probability": round(pathogenic_probability, 6),
+        "pathogenic_probability_percent": round(pathogenic_probability * 100.0, 1),
+        "threshold": threshold,
+        "sequence_length_used": sequence_length_used,
+        "model": "DNABERT-2 fine-tuned on a ClinVar alternate-sequence research dataset",
+        "test_auc_roc": 0.5928,
+    }
+    user_prompt = (
+        "Write the explanation paragraph for this model output. "
+        "The explanation must be understandable to a beginner and must stay research/demo-only.\n\n"
+        f"Model output JSON:\n{json.dumps(context, indent=2)}"
+    )
+
+    try:
+        client = OpenAI(api_key=openai_api_key, timeout=openai_timeout)
+        response = client.responses.create(
+            model=openai_model,
+            instructions=OPENAI_SYSTEM_INSTRUCTIONS,
+            input=user_prompt,
+            max_output_tokens=300,
+        )
+        output_text = str(getattr(response, "output_text", "")).strip()
+        if not output_text:
+            print("OpenAI explanation response was empty. Using rule-based explanation.")
+            return fallback
+
+        parsed = _extract_json_object(output_text)
+        explanation = str(parsed.get("explanation", "")).strip()
+        if not explanation:
+            print("OpenAI explanation JSON did not include explanation. Using rule-based explanation.")
+            return fallback
+
+        enhanced = dict(fallback)
+        enhanced["explanation"] = explanation
+        return enhanced
+    except Exception as exc:  # pragma: no cover - network/API failures vary.
+        print(f"OpenAI explanation failed: {type(exc).__name__}: {exc}. Using rule-based explanation.")
+        return fallback
+
+
+def generate_explanation(
+    prediction_class: int,
+    prediction_label: str,
+    risk_level: str,
+    benign_probability: float,
+    pathogenic_probability: float,
+    threshold: float,
+    variant_name: str | None = None,
+    gene: str | None = None,
+    sequence_length_used: int | None = None,
+    use_openai: bool = False,
+    openai_api_key: str = "",
+    openai_model: str = "gpt-4.1-mini",
+    openai_timeout: float = 12.0,
+) -> dict:
+    fallback = _generate_rule_based_explanation(
+        prediction_class=prediction_class,
+        prediction_label=prediction_label,
+        risk_level=risk_level,
+        benign_probability=benign_probability,
+        pathogenic_probability=pathogenic_probability,
+        threshold=threshold,
+        variant_name=variant_name,
+        gene=gene,
+        sequence_length_used=sequence_length_used,
+    )
+
+    if not use_openai:
+        return fallback
+    if not openai_api_key:
+        print("USE_OPENAI_EXPLANATION is true, but OPENAI_API_KEY is missing. Using rule-based explanation.")
+        return fallback
+
+    return _generate_openai_explanation(
+        fallback=fallback,
+        prediction_class=prediction_class,
+        prediction_label=prediction_label,
+        risk_level=risk_level,
+        benign_probability=benign_probability,
+        pathogenic_probability=pathogenic_probability,
+        threshold=threshold,
+        openai_api_key=openai_api_key,
+        openai_model=openai_model,
+        openai_timeout=openai_timeout,
+        variant_name=variant_name,
+        gene=gene,
+        sequence_length_used=sequence_length_used,
+    )

backend/requirements.txt

@@ -6,3 +6,4 @@ safetensors
 pydantic
 numpy
 python-dotenv
+openai

frontend/README.md

@@ -4,7 +4,9 @@ Next.js frontend for the Variant Risk Explainer research demo.
 
 The app connects to the FastAPI backend, submits a DNA sequence to
 `POST /analyze`, shows the DNABERT-2 prediction result, and displays backend
-health/model status.
+health/model status. The result card also displays the backend's rule-based
+or optional OpenAI explanation, confidence level, recommendation, and
+limitations.
 
 This is for research/demo use only. It is not a clinical diagnostic system.
 
@@ -66,7 +68,13 @@ NEXT_PUBLIC_API_URL=http://127.0.0.1:8001
 5. Click `Analyze Variant`.
 
 The result card shows benign/pathogenic probabilities, threshold, model name,
-and sequence length used after center cropping.
+sequence length used after center cropping, and a beginner-friendly explanation.
+
+The explanation is generated from the backend model output and threshold. It is
+not medical advice and is not a clinical interpretation. If the backend has
+`USE_OPENAI_EXPLANATION=true`, the backend may use OpenAI to improve the
+explanation paragraph. Do not put the OpenAI API key in the frontend; keep it in
+`backend/.env` only.
 
 ## Safety Notice
 

frontend/app/globals.css

@@ -432,6 +432,24 @@ dd {
   line-height: 1.55;
 }
 
+.explanation p {
+  margin-bottom: 8px;
+}
+
+.recommendationBlock {
+  margin-top: 16px;
+  border: 1px solid #d8c8b0;
+  border-radius: 8px;
+  padding: 12px;
+  background: #fffaf0;
+  color: #4e3c34;
+  line-height: 1.5;
+}
+
+.recommendationBlock p {
+  margin-bottom: 0;
+}
+
 .limitations {
   margin-top: 18px;
   border-top: 1px solid var(--border);

frontend/components/ResultCard.tsx

@@ -95,7 +95,33 @@ export function ResultCard({ error, isLoading, result }: ResultCardProps) {
         </div>
       </div>
 
-      <p className="disclaimer">{result.disclaimer}</p>
+      <div className="explanation">
+        <h3>Explanation</h3>
+        <p>{result.explanation}</p>
+        <p>
+          <strong>Confidence level:</strong> {result.confidence_level}
+        </p>
+      </div>
+
+      <div className="recommendationBlock">
+        <h3>Recommendation</h3>
+        <p>{result.recommendation}</p>
+      </div>
+
+      <div className="limitations">
+        <h3>Limitations</h3>
+        <ul>
+          {result.limitations.map((limitation) => (
+            <li key={limitation}>{limitation}</li>
+          ))}
+        </ul>
+      </div>
+
+      <p className="disclaimer">
+        <strong>Research/demo only. Not for clinical diagnosis.</strong>
+        <br />
+        {result.disclaimer}
+      </p>
     </section>
   );
 }

frontend/types.ts

@@ -16,6 +16,10 @@ export type AnalyzeResponse = {
   threshold: number;
   model_name: string;
   sequence_length_used: number;
+  explanation: string;
+  confidence_level: string;
+  recommendation: string;
+  limitations: string[];
   disclaimer: string;
 };