Add WhatsApp multi-user broadcast system

README.md

@@ -152,6 +152,8 @@ in a different directory.
 | `REACT_APP_SUPABASE_URL` | Yes | Supabase frontend project URL |
 | `REACT_APP_SUPABASE_ANON_KEY` | Yes | Supabase browser authentication |
 | `OPENAI_API_KEY` | Only for `/ask` | LangChain/OpenAI question answering |
+| `GEMINI_API_KEY` | Optional | Portfolio Doctor explanations |
+| `GEMINI_SCREENER_API_KEY` | Optional | Isolated quota for ML screener explanations |
 | `TWILIO_ACCOUNT_SID` | Only for WhatsApp | Twilio account identifier |
 | `TWILIO_AUTH_TOKEN` | Only for WhatsApp | Twilio authentication |
 | `TWILIO_WHATSAPP_FROM` | Optional | WhatsApp sender, defaults to Twilio sandbox sender |

backend/api_v2.py

@@ -17,6 +17,8 @@ from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field
 
 from agents.pipeline import run_pipeline
+from backend.portfolio_ai import generate_portfolio_report
+from backend.screener_explainer import explain_screener_prediction
 from data.fetch_prices import (
     SCREENER_UNIVERSE,
     fetch_gold_price_inr,
@@ -133,7 +135,7 @@ def health(request: Request):
 
 
 @router.get("/signal/full/{symbol}", response_model=ApiSuccessEnvelope)
-def signal_full(request: Request, symbol: str):
+def signal_full(request: Request, symbol: str, explain_screener: bool = False):
     """Complete HistoricalService analysis — single source of truth for
     AI Screener, Portfolio Doctor, Full Analysis, and WhatsApp."""
     sym = symbol.upper()
@@ -141,11 +143,13 @@ def signal_full(request: Request, symbol: str):
         sym = sym + ".NS"
     try:
         service = HistoricalService()
-        analysis = service.analyze(sym)
+        analysis = service.analyze(sym, include_explanation=not explain_screener)
         data = analysis.model_dump()
         # The full-analysis response is the UI contract. Keep nested values
         # intact so clients do not need legacy aliases or local calculations.
         data["sentiment"] = data.pop("sentiment_details", {})
+        if explain_screener:
+            data["screener_explanation"] = explain_screener_prediction(data)
         return success(request, data, "Full analysis completed successfully.")
     except ValueError as exc:
         return error(request, status_code=404, code="SYMBOL_NOT_FOUND", message=str(exc))
@@ -333,7 +337,7 @@ def portfolio_analyze(request: Request, payload: PortfolioAnalyzeRequest):
         symbol = holding.symbol.strip().upper()
         normalized = symbol if symbol.endswith(".NS") or symbol in {"GC=F", "SI=F"} else f"{symbol}.NS"
         try:
-            analysis = service.analyze(normalized)
+            analysis = service.analyze(normalized, include_explanation=False)
             invested = holding.quantity * holding.buy_price
             market_value = holding.quantity * analysis.current_price
             holdings.append({
@@ -364,10 +368,82 @@ def portfolio_analyze(request: Request, payload: PortfolioAnalyzeRequest):
             logger.exception("v2.portfolio.holding_failed", extra={"request_id": _request_id(request), "symbol": symbol})
             holdings.append({"symbol": symbol, "status": "failed", "error": {"code": "ANALYSIS_UNAVAILABLE", "message": "Could not analyze this holding."}})
 
-    successful = sum(item["status"] == "analyzed" for item in holdings)
+    successful_holdings = [item for item in holdings if item["status"] == "analyzed"]
+    successful = len(successful_holdings)
+    ai_report = None
+
+    if successful_holdings:
+        total_invested = sum(item["invested_amount"] for item in successful_holdings)
+        total_market_value = sum(item["market_value"] for item in successful_holdings)
+        risk_distribution = {
+            risk: sum(item["overall_risk"].upper() == risk for item in successful_holdings)
+            for risk in ("HIGH", "MEDIUM", "LOW")
+        }
+        trends = [item["trend"] for item in successful_holdings]
+        sentiments = [item["sentiment"] for item in successful_holdings]
+        expected_returns = [
+            item["expected_return"]
+            for item in successful_holdings
+            if item["expected_return"] is not None
+        ]
+        confidence = sum(item["confidence"] for item in successful_holdings) / successful
+        overall_risk = next(
+            risk for risk in ("HIGH", "MEDIUM", "LOW") if risk_distribution[risk]
+        )
+        portfolio_analysis = {
+            "symbol": "PORTFOLIO",
+            "portfolio_summary": {
+                "positions": successful,
+                "invested_amount": round(total_invested, 2),
+                "market_value": round(total_market_value, 2),
+                "pnl": round(total_market_value - total_invested, 2),
+                "pnl_percent": round(
+                    ((total_market_value - total_invested) / total_invested) * 100, 2
+                ) if total_invested else 0,
+                "risk_distribution": risk_distribution,
+            },
+            "holdings": [
+                {
+                    key: item[key]
+                    for key in (
+                        "symbol", "quantity", "current_price", "pnl", "pnl_percent",
+                        "recommendation", "confidence", "overall_risk", "trend",
+                        "sentiment", "agreement", "model_agreement", "reasoning",
+                    )
+                }
+                for item in successful_holdings
+            ],
+            "trend": trends[0] if len(set(trends)) == 1 else "MIXED",
+            "sentiment": sentiments[0] if len(set(sentiments)) == 1 else "mixed",
+            "recommendation": "; ".join(
+                f"{item['symbol']}: {item['recommendation']}" for item in successful_holdings
+            ),
+            "confidence": round(confidence, 2),
+            "overall_score": round(
+                sum(item["overall_score"] for item in successful_holdings) / successful, 2
+            ),
+            "overall_risk": overall_risk,
+            "expected_return": (
+                sum(expected_returns) / len(expected_returns) if expected_returns else None
+            ),
+            "agreement": "mixed" if len({item["agreement"] for item in successful_holdings}) > 1
+            else successful_holdings[0]["agreement"],
+            "model_agreement": all(item["model_agreement"] for item in successful_holdings),
+        }
+        try:
+            ai_report = generate_portfolio_report(analysis=portfolio_analysis)
+        except Exception:
+            logger.exception("v2.portfolio.explanation_failed", extra={"request_id": _request_id(request)})
+
     return success(
         request,
-        {"holdings": holdings, "count": len(holdings), "successful": successful, "failed": len(holdings) - successful},
+        {
+            "holdings": holdings,
+            "count": len(holdings),
+            "successful": successful,
+            "failed": len(holdings) - successful,
+            "ai_report": ai_report.model_dump() if ai_report else None,
+        },
         "Portfolio analyzed successfully." if successful == len(holdings) else "Portfolio analysis completed with some unavailable holdings.",
     )
 

backend/portfolio_ai/llm_explainer.py

@@ -61,7 +61,7 @@ from backend.utils.logging import redact_sensitive_data
 logger = logging.getLogger(__name__)
 
 MODEL_NAME: str = os.getenv("GEMINI_MODEL", "gemini-2.5-flash")
-API_KEY: Optional[str] = os.getenv("GEMINI_API_KEY")
+API_KEY: Optional[str] = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
 
 MAX_TOKENS: int = 600
 

backend/screener_explainer.py

@@ -0,0 +1,167 @@
+"""Plain-English explanations for deterministic screener predictions."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+def explain_screener_prediction(analysis: dict[str, Any]) -> dict[str, Any]:
+    """Explain an existing signal with a dedicated Gemini key, never alter it."""
+    api_key = os.getenv("GEMINI_SCREENER_API_KEY")
+    if not api_key:
+        return _fallback_explanation(analysis, "Dedicated Gemini screener key is not configured.")
+
+    model = os.getenv("GEMINI_SCREENER_MODEL", "gemini-2.5-flash")
+    prompt = _build_prompt(analysis)
+    try:
+        response = requests.post(
+            f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent",
+            headers={"x-goog-api-key": api_key},
+            json={
+                "systemInstruction": {
+                    "parts": [{"text": _SYSTEM_PROMPT}],
+                },
+                "contents": [{"role": "user", "parts": [{"text": prompt}]}],
+                "generationConfig": {
+                    "temperature": 0.2,
+                    "maxOutputTokens": 700,
+                    "responseMimeType": "application/json",
+                },
+            },
+            timeout=20,
+        )
+        response.raise_for_status()
+        body = response.json()
+        text = body["candidates"][0]["content"]["parts"][0]["text"]
+        result = _validate_report(json.loads(_strip_code_fence(text)))
+        result["recommendations"] = [_fixed_recommendation(analysis)]
+        result["is_fallback"] = False
+        result["explanation_source"] = "Gemini"
+        return result
+    except Exception as exc:
+        logger.warning(
+            "screener.gemini_explanation_failed",
+            extra={"symbol": analysis.get("symbol"), "error": str(exc)},
+        )
+        return _fallback_explanation(analysis, "Gemini explanation is temporarily unavailable.")
+
+
+_SYSTEM_PROMPT = """You explain an already-computed stock model result for a retail trader.
+Do not perform new analysis, change the signal, confidence, target price, or risk
+rating, and do not add trade instructions or recommend other securities. Use only
+the supplied deterministic data. Explain what the SHAP drivers and indicators
+mean, while distinguishing correlation/context from proven causation. If the data
+does not support a conclusion, say so. Return JSON only with exactly these fields:
+summary (string), strengths (string array), risks (string array), recommendations
+(string array), outlook (string), confidence_note (string)."""
+
+
+def _build_prompt(analysis: dict[str, Any]) -> str:
+    sentiment = analysis.get("sentiment")
+    if isinstance(sentiment, dict):
+        sentiment = sentiment.get("dominant", sentiment.get("label", "unavailable"))
+    expected_return = analysis.get("expected_return")
+    payload = {
+        "symbol": analysis.get("symbol"),
+        "current_price_inr": analysis.get("current_price"),
+        "predicted_price_inr": analysis.get("predicted_price"),
+        "expected_return_percent": (
+            round(float(expected_return) * 100, 2)
+            if expected_return is not None
+            else None
+        ),
+        "model_signal": analysis.get("recommendation"),
+        "confidence_percent": analysis.get("confidence"),
+        "risk_rating": analysis.get("overall_risk"),
+        "trend": analysis.get("trend"),
+        "sentiment": sentiment,
+        "sentiment_score": analysis.get("sentiment_score"),
+        "model_agreement": analysis.get("model_agreement"),
+        "agreement": analysis.get("agreement"),
+        "available_models": analysis.get("explainability", {}).get("available_models", []),
+        "technical_indicators": analysis.get("technical_indicators", {}),
+        "shap_drivers": analysis.get("shap", {}).get("features", []),
+        "deterministic_reasoning": analysis.get("reasoning", []),
+        "risk_metrics": analysis.get("risk", {}),
+    }
+    return "Explain this prediction using only the following JSON data:\n" + json.dumps(
+        payload, ensure_ascii=True, allow_nan=False
+    )
+
+
+def _validate_report(data: Any) -> dict[str, Any]:
+    if not isinstance(data, dict) or not isinstance(data.get("summary"), str):
+        raise ValueError("Gemini returned an invalid explanation schema.")
+
+    def clean_list(name: str, limit: int) -> list[str]:
+        value = data.get(name, [])
+        if not isinstance(value, list):
+            return []
+        return [item.strip()[:400] for item in value if isinstance(item, str) and item.strip()][:limit]
+
+    return {
+        "summary": data["summary"].strip()[:1200],
+        "strengths": clean_list("strengths", 4),
+        "risks": clean_list("risks", 4),
+        "recommendations": clean_list("recommendations", 1),
+        "outlook": str(data.get("outlook", "")).strip()[:600],
+        "confidence_note": str(data.get("confidence_note", "")).strip()[:600],
+    }
+
+
+def _fixed_recommendation(analysis: dict[str, Any]) -> str:
+    symbol = analysis.get("symbol", "This stock")
+    recommendation = analysis.get("recommendation", "Unavailable")
+    return f"Existing model signal for {symbol}: {recommendation}. Gemini does not change it."
+
+
+def _fallback_explanation(analysis: dict[str, Any], reason: str) -> dict[str, Any]:
+    drivers = [
+        str(item).strip()
+        for item in analysis.get("reasoning", [])
+        if isinstance(item, str) and item.strip()
+    ][:3]
+    shap_features = analysis.get("shap", {}).get("features", [])
+    for feature in shap_features[:3]:
+        if isinstance(feature, dict) and feature.get("name"):
+            drivers.append(f"SHAP model driver: {feature['name']} (contribution {feature.get('value', 'unavailable')}).")
+
+    recommendation = analysis.get("recommendation", "unavailable")
+    confidence = analysis.get("confidence")
+    symbol = analysis.get("symbol", "This stock")
+    confidence_text = f" at {confidence}% confidence" if confidence is not None else ""
+    if not drivers:
+        drivers = ["The deterministic model did not return readable feature-level reasoning."]
+
+    return {
+        "summary": (
+            f"{reason} {symbol} has an existing {recommendation} model signal{confidence_text}. "
+            "The points below come from the deterministic model output; they do not change its signal."
+        ),
+        "strengths": drivers[:4],
+        "risks": ["This explanation is a deterministic fallback, not a Gemini-generated interpretation."],
+        "recommendations": [_fixed_recommendation(analysis)],
+        "outlook": f"The model's existing trend assessment is {analysis.get('trend', 'unavailable')}.",
+        "confidence_note": (
+            f"Model confidence is {confidence}% and agreement is {analysis.get('agreement', 'unavailable')}."
+            if confidence is not None
+            else "The model did not provide a confidence value."
+        ),
+        "is_fallback": True,
+        "explanation_source": "Deterministic fallback",
+    }
+
+
+def _strip_code_fence(text: str) -> str:
+    value = text.strip()
+    if value.startswith("```"):
+        value = value.removeprefix("```json").removeprefix("```")
+        value = value.removesuffix("```")
+    return value.strip()

backend/wealth/historical_service.py

@@ -103,7 +103,7 @@ class HistoricalService:
         self._sentiment = sentiment_provider or self._default_sentiment_provider()
         self._fusion    = fusion_engine      or FusionEngine()
 
-    def analyze(self, symbol: str) -> HistoricalAnalysis:
+    def analyze(self, symbol: str, *, include_explanation: bool = True) -> HistoricalAnalysis:
         """Run research, predictions, fusion, and response mapping for a symbol."""
         normalized_symbol = self._validate_symbol(symbol)
         started_at = time.perf_counter()
@@ -123,7 +123,12 @@ class HistoricalService:
                 predicted_price=predicted_price,
             )
             analysis = self._build_analysis(
-                normalized_symbol, research_data, predictions, sentiment, fusion
+                normalized_symbol,
+                research_data,
+                predictions,
+                sentiment,
+                fusion,
+                include_explanation=include_explanation,
             )
         except HistoricalServiceError:
             raise
@@ -252,6 +257,7 @@ class HistoricalService:
         predictions: Mapping[str, Mapping[str, Any]],
         sentiment: Mapping[str, Any],
         fusion: FusionResult,
+        include_explanation: bool = True,
     ) -> HistoricalAnalysis:
         lstm = predictions["lstm"]
         rf = predictions["random_forest"]
@@ -282,29 +288,30 @@ class HistoricalService:
             reasoning=list(fusion.reasoning),
         )
 
-        try:
-            analysis.ai_report = generate_portfolio_report(
-                analysis=self._analysis_payload(analysis)
-            )
-        except Exception as exc:
-            logger.warning(
-                "portfolio_ai_report_failed",
-                extra={"ticker": symbol, "error": str(exc)},
-            )
-            analysis.ai_report = PortfolioAIReport(
-                summary="Portfolio analysis completed using deterministic AI models.",
-                strengths=[
-                    f"Detected market trend: {analysis.trend}.",
-                    f"Overall sentiment: {analysis.sentiment}.",
-                ],
-                risks=[
-                    "AI explanation service unavailable.",
-                    "Only deterministic analysis is shown.",
-                ],
-                recommendations=[analysis.recommendation],
-                outlook="Future outlook follows the deterministic prediction generated by TradeMind.",
-                confidence_note=f"Model confidence is {analysis.confidence}%.",
-            )
+        if include_explanation:
+            try:
+                analysis.ai_report = generate_portfolio_report(
+                    analysis=self._analysis_payload(analysis)
+                )
+            except Exception as exc:
+                logger.warning(
+                    "portfolio_ai_report_failed",
+                    extra={"ticker": symbol, "error": str(exc)},
+                )
+                analysis.ai_report = PortfolioAIReport(
+                    summary="Portfolio analysis completed using deterministic AI models.",
+                    strengths=[
+                        f"Detected market trend: {analysis.trend}.",
+                        f"Overall sentiment: {analysis.sentiment}.",
+                    ],
+                    risks=[
+                        "AI explanation service unavailable.",
+                        "Only deterministic analysis is shown.",
+                    ],
+                    recommendations=[analysis.recommendation],
+                    outlook="Future outlook follows the deterministic prediction generated by TradeMind.",
+                    confidence_note=f"Model confidence is {analysis.confidence}%.",
+                )
 
         return analysis
 

frontend/package-lock.json

@@ -40,7 +40,7 @@
         "cross-env": "^7.0.3"
       },
       "engines": {
-        "node": ">=18.0.0 <21.0.0",
+        "node": "24.x",
         "npm": ">=9.0.0"
       }
     },

frontend/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "engines": {
-    "node": ">=18.0.0 <21.0.0",
+    "node": "24.x",
     "npm": ">=9.0.0"
   },
   "dependencies": {

frontend/src/components/cards/SignalCard.jsx

@@ -5,6 +5,7 @@ import { Badge } from "../ui/Badge";
 import { Tabs } from "../ui/Tabs";
 import { MetricCard } from "../ui/MetricCard";
 import { PriceAreaChart } from "../charts/PriceAreaChart";
+import { ScreenerExplanationPanel } from "../screener/ScreenerExplanationPanel";
 import { parseConf } from "../../utils/formatters";
 import { SIGNAL_COLORS } from "../../constants/stocks";
 import { Sparkles, Brain, AlertTriangle, Activity } from "lucide-react";
@@ -347,6 +348,8 @@ export function SignalCard({ signal, isMobile }) {
                         border: "1px solid var(--border)",
                       }}
                     >
+                      <ScreenerExplanationPanel explanation={signal.screener_explanation} />
+
                       <div
                         className="mono"
                         style={{

frontend/src/components/portfolio/AIInvestmentReport.jsx

@@ -32,7 +32,7 @@ export function AIInvestmentReport({ report }) {
     "LSTM",
     "FinBERT",
     "Fusion Engine",
-    "OpenAI Explanation",
+    isDeterministic ? "Deterministic Fallback" : "Gemini Explanation",
   ];
 
   // Requirement 5: Framer Motion animation variants

frontend/src/components/screener/ScreenerExplanationPanel.jsx

@@ -0,0 +1,45 @@
+import React from "react";
+import { BrainCircuit, Sparkles } from "lucide-react";
+
+export function ScreenerExplanationPanel({ explanation }) {
+  if (!explanation) return null;
+
+  const drivers = explanation.strengths || [];
+  const risks = explanation.risks || [];
+
+  return (
+    <section className="sc-explanation" aria-label="Prediction explanation">
+      <div className="sc-explanation-header">
+        <div className="sc-explanation-title">
+          <BrainCircuit size={15} color="var(--color-teal)" />
+          <span>WHY THE MODEL MADE THIS PREDICTION</span>
+        </div>
+        <span className={explanation.is_fallback ? "sc-explanation-source is-fallback" : "sc-explanation-source"}>
+          {explanation.is_fallback ? "Model data" : <><Sparkles size={12} /> Gemini</>}
+        </span>
+      </div>
+
+      <p className="sc-explanation-summary">{explanation.summary}</p>
+
+      {drivers.length > 0 && (
+        <div className="sc-explanation-group">
+          <h4>Supporting evidence</h4>
+          <ul>{drivers.map((driver, index) => <li key={index}>{driver}</li>)}</ul>
+        </div>
+      )}
+
+      {risks.length > 0 && (
+        <div className="sc-explanation-group sc-explanation-risks">
+          <h4>Limitations and risks</h4>
+          <ul>{risks.map((risk, index) => <li key={index}>{risk}</li>)}</ul>
+        </div>
+      )}
+
+      {explanation.confidence_note && (
+        <p className="sc-explanation-confidence">{explanation.confidence_note}</p>
+      )}
+    </section>
+  );
+}
+
+export default ScreenerExplanationPanel;

frontend/src/components/screener/ScreenerStockCard.jsx

@@ -15,6 +15,7 @@ import { Card } from "../ui/Card";
 import { Badge } from "../ui/Badge";
 import { Typography } from "../ui/Typography";
 import { parseConf } from "../../utils/formatters";
+import { ScreenerExplanationPanel } from "./ScreenerExplanationPanel";
 
 export function ScreenerStockCard({
   stock,
@@ -358,6 +359,8 @@ export function ScreenerStockCard({
         </div>
       </div>
 
+      <ScreenerExplanationPanel explanation={stock.screener_explanation} />
+
       {/* Mini Recharts Sparkline */}
       {stock.history?.length > 0 && (
         <div style={{ height: "32px", width: "100%" }}>

frontend/src/pages/Dashboard/DashboardPage.jsx

@@ -1,6 +1,5 @@
 import React, { useState, useEffect } from "react";
 import { useNavigate, useOutletContext } from "react-router-dom";
-import CountUp from "react-countup";
 import {
   Sparkles,
   ArrowRight,
@@ -8,7 +7,7 @@ import {
   Zap,
 } from "lucide-react";
 import { PageTransition } from "../../components/animations/PageTransition";
-import { Card, MetricCard } from "../../components/ui/Card";
+import { Card } from "../../components/ui/Card";
 import { Button } from "../../components/ui/Button";
 import { Badge } from "../../components/ui/Badge";
 import { DashboardSkeleton } from "../../components/dashboard/DashboardSkeleton";
@@ -116,53 +115,6 @@ export function DashboardPage() {
           </div>
         </section>
 
-        {/* SECTION 2: QUICK METRICS */}
-        <section style={{ marginBottom: "28px" }}>
-          <div className="db-metrics-grid">
-            <MetricCard
-              label="PORTFOLIO VALUE"
-              value={<>₹<CountUp end={425800} duration={1.5} separator="," /></>}
-              sub="₹4.25 Lakh Total"
-              color="var(--text-primary)"
-            />
-
-            <MetricCard
-              label="TODAY'S P/L"
-              value={<>+₹<CountUp end={6420} duration={1.5} separator="," /> (+1.53%)</>}
-              sub="Net Daily Gain"
-              color="var(--success)"
-            />
-
-            <MetricCard
-              label="PORTFOLIO HEALTH"
-              value={<><CountUp end={78} duration={1.5} />/100</>}
-              sub="Optimal Allocation"
-              color="var(--color-teal)"
-            />
-
-            <MetricCard
-              label="AI CONFIDENCE"
-              value={<><CountUp end={92} duration={1.5} />%</>}
-              sub="Multi-Model Agreement"
-              color="var(--color-teal)"
-            />
-
-            <MetricCard
-              label="EXPECTED RETURN"
-              value={<><CountUp end={14.2} decimals={1} duration={1.5} />%</>}
-              sub="Annualized Forecast"
-              color="var(--accent-blue)"
-            />
-
-            <MetricCard
-              label="RISK PROFILE"
-              value="LOW-MED"
-              sub="Balanced Risk Index"
-              color="var(--color-gold)"
-            />
-          </div>
-        </section>
-
         {/* SECTION 3: MARKET OVERVIEW */}
         <MarketOverviewSection commodities={commodities} marketQuotes={marketQuotes} />
 

frontend/src/pages/PortfolioDoctor/PortfolioDoctorPage.jsx

@@ -74,36 +74,43 @@ function computeReport(rawHoldings, requestId, aiReport) {
       : Math.round(100 / n),
   }));
 
-  // ── Risk ──
-  const riskCounts = { HIGH: 0, MEDIUM: 0, LOW: 0 };
-  holdingsWithWeight.forEach((h) => {
-    const r = (h.overall_risk || "").toUpperCase();
-    if (r.includes("HIGH"))   riskCounts.HIGH++;
-    else if (r.includes("MEDIUM")) riskCounts.MEDIUM++;
-    else riskCounts.LOW++;
+  // ── Risk distribution by current portfolio weight ──
+  const riskWeights = { HIGH: 0, MEDIUM: 0, LOW: 0 };
+  holdingsWithWeight.forEach((holding) => {
+    const risk = (holding.overall_risk || "MEDIUM").toUpperCase();
+    const tier = risk.includes("HIGH") ? "HIGH" : risk.includes("LOW") ? "LOW" : "MEDIUM";
+    riskWeights[tier] += safeNum(holding.weight);
   });
-  const overallRisk = riskCounts.HIGH > 0 ? "HIGH" : riskCounts.MEDIUM > 0 ? "MEDIUM" : "LOW";
-
-  // ── AI Confidence — backend sends 0–100 or 0–1; normalise to 0–100 ──
-  const rawConf = rawHoldings.reduce((s, h) => s + safeNum(h.confidence), 0) / n;
-  // If average > 1 it's already in percent; otherwise multiply by 100
-  const aiConfidence = clamp100(rawConf > 1 ? rawConf : rawConf * 100);
+  const riskPriority = { HIGH: 3, MEDIUM: 2, LOW: 1 };
+  const overallRisk = Object.keys(riskWeights).sort((left, right) =>
+    riskWeights[right] - riskWeights[left] || riskPriority[right] - riskPriority[left]
+  )[0];
+
+  // Confidence is supplied as either 0–1 or 0–100 by model responses.
+  const confidenceWeight = (holding) => totalMarketValue > 0
+    ? safeNum(holding.market_value) / totalMarketValue
+    : 1 / n;
+  const aiConfidence = clamp100(rawHoldings.reduce((sum, holding) => {
+    const confidence = safeNum(holding.confidence);
+    return sum + (confidence > 1 ? confidence : confidence * 100) * confidenceWeight(holding);
+  }, 0));
 
   // ── Diversification (Herfindahl) ──
   const hhi = holdingsWithWeight.reduce((s, h) => s + Math.pow(h.weight / 100, 2), 0);
   const diversificationScore = Math.max(20, Math.round((1 - hhi) * 100));
 
   // ── Expected return & volatility from backend per-holding data ──
-  const validReturns = rawHoldings
-    .map((h) => safeNum(h.expected_return))
-    .filter((v) => v !== 0);
-  // expected_return from backend is a fraction (e.g. 0.08 = 8%)
-  const avgExpectedReturn = validReturns.length > 0
-    ? +((validReturns.reduce((s, v) => s + v, 0) / validReturns.length) * 100).toFixed(1)
-    : (overallRisk === "HIGH" ? 14.5 : overallRisk === "MEDIUM" ? 11.2 : 8.5);
-
-  const expectedVolatility = overallRisk === "HIGH" ? 22.4
-    : overallRisk === "MEDIUM" ? 14.8 : 9.6;
+  const validReturns = rawHoldings.filter((holding) =>
+    holding.expected_return != null && Number.isFinite(Number(holding.expected_return))
+  );
+  const returnWeightTotal = validReturns.reduce((sum, holding) =>
+    sum + confidenceWeight(holding), 0
+  );
+  const avgExpectedReturn = validReturns.length && returnWeightTotal > 0
+    ? +((validReturns.reduce((sum, holding) =>
+      sum + safeNum(holding.expected_return) * confidenceWeight(holding), 0
+    ) / returnWeightTotal) * 100).toFixed(1)
+    : null;
 
   // ── Health Score — composite of 5 factors, each 0–20 ──
   //   1. AI Confidence component (0–20)
@@ -113,16 +120,19 @@ function computeReport(rawHoldings, requestId, aiReport) {
   //   3. Risk component: LOW=20, MEDIUM=12, HIGH=4
   const riskComponent = overallRisk === "LOW" ? 20 : overallRisk === "MEDIUM" ? 12 : 4;
   //   4. Return component: positive return up to 20%, capped at 20
-  const retComponent = Math.min(20, Math.max(0, avgExpectedReturn));
+  const retComponent = avgExpectedReturn == null ? 0 : Math.min(20, Math.max(0, avgExpectedReturn));
   //   5. Model score component (0–20)
-  const avgModelScore = rawHoldings.reduce((s, h) => s + safeNum(h.overall_score, 5), 0) / n;
+  const avgModelScore = rawHoldings.reduce((sum, holding) =>
+    sum + safeNum(holding.overall_score, 5) * confidenceWeight(holding), 0
+  );
   const scoreComponent = Math.min(20, (avgModelScore / 10) * 20);
 
   const rawHealth = confComponent + divComponent + riskComponent + retComponent + scoreComponent;
   const healthScore = clamp100(rawHealth);
 
   // ── Market Outlook — derived from risk + return, not hardcoded ──
-  const marketOutlook = avgExpectedReturn >= 10 && overallRisk !== "HIGH" ? "BULLISH"
+  const marketOutlook = avgExpectedReturn == null ? "UNAVAILABLE"
+    : avgExpectedReturn >= 10 && overallRisk !== "HIGH" ? "BULLISH"
     : avgExpectedReturn <= 0 || overallRisk === "HIGH" ? "BEARISH"
     : "NEUTRAL";
 
@@ -135,7 +145,7 @@ function computeReport(rawHoldings, requestId, aiReport) {
     healthScore,
     overallRisk,
     expectedReturn: avgExpectedReturn,
-    expectedVolatility,
+    expectedVolatility: null,
     diversificationScore,
     aiConfidence,
     marketOutlook,
@@ -144,6 +154,36 @@ function computeReport(rawHoldings, requestId, aiReport) {
   };
 }
 
+function calculatePortfolioVolatility(holdings, quotes) {
+  const positions = holdings.map((holding) => {
+    const symbol = (holding.symbol || "").replace(/\.NS$/i, "").toUpperCase();
+    const history = quotes[symbol]?.history || [];
+    return {
+      quantity: safeNum(holding.quantity),
+      prices: new Map(history
+        .filter((point) => point?.date && Number.isFinite(Number(point.price)) && Number(point.price) > 0)
+        .map((point) => [point.date, Number(point.price)])),
+    };
+  });
+
+  if (!positions.length || positions.some((position) => position.prices.size < 2)) return null;
+
+  const dates = [...positions[0].prices.keys()]
+    .filter((date) => positions.every((position) => position.prices.has(date)))
+    .sort();
+  const portfolioValues = dates.map((date) => positions.reduce(
+    (total, position) => total + position.quantity * position.prices.get(date), 0
+  ));
+  const returns = portfolioValues.slice(1).map((value, index) =>
+    value / portfolioValues[index] - 1
+  ).filter(Number.isFinite);
+
+  if (returns.length < 2) return null;
+  const mean = returns.reduce((sum, value) => sum + value, 0) / returns.length;
+  const variance = returns.reduce((sum, value) => sum + ((value - mean) ** 2), 0) / (returns.length - 1);
+  return +(Math.sqrt(variance * 252) * 100).toFixed(1);
+}
+
 function applyMarketQuotes(report, quotes) {
   const holdings = report.holdings.map((holding) => {
     const symbol = (holding.symbol || "").replace(/\.NS$/i, "").toUpperCase();
@@ -165,26 +205,17 @@ function applyMarketQuotes(report, quotes) {
       invested_amount: investedAmount,
       pnl,
       pnl_percent: investedAmount > 0 ? +((pnl / investedAmount) * 100).toFixed(2) : 0,
+      expected_return: safeNum(holding.predicted_price) > 0
+        ? (safeNum(holding.predicted_price) / Number(quote.price)) - 1
+        : holding.expected_return,
       market_price_as_of: quote.as_of,
     };
   });
 
-  const totalInvested = holdings.reduce((sum, holding) => sum + safeNum(holding.invested_amount), 0);
-  const totalMarketValue = holdings.reduce((sum, holding) => sum + safeNum(holding.market_value), 0);
-  const totalPnl = totalMarketValue - totalInvested;
-
+  const updatedReport = computeReport(holdings, report.requestId, report.ai_report);
   return {
-    ...report,
-    holdings: holdings.map((holding) => ({
-      ...holding,
-      weight: totalMarketValue > 0
-        ? Math.round((safeNum(holding.market_value) / totalMarketValue) * 100)
-        : holding.weight,
-    })),
-    totalInvested,
-    totalMarketValue,
-    totalPnl,
-    totalPnlPct: totalInvested > 0 ? +((totalPnl / totalInvested) * 100).toFixed(1) : 0,
+    ...updatedReport,
+    expectedVolatility: calculatePortfolioVolatility(holdings, quotes),
   };
 }
 
@@ -241,9 +272,9 @@ export function PortfolioDoctorPage() {
       setLoaderStep(0);
       setErrorDetails(null);
       const demoHoldings = [
-        { symbol: "RELIANCE.NS", quantity: 10, buy_price: 2450, current_price: 2540, invested_amount: 24500, market_value: 25400, pnl: 900, pnl_percent: 3.67, overall_risk: "LOW", overall_score: 8.4, recommendation: "BUY", confidence: 0.88, trend: "BULLISH", reasoning: ["Momentum remains constructive after a healthy pullback.", "Diversification is strong across sector leaders."] },
-        { symbol: "TCS.NS", quantity: 8, buy_price: 3850, current_price: 3720, invested_amount: 30800, market_value: 29760, pnl: -1040, pnl_percent: -3.38, overall_risk: "LOW", overall_score: 7.8, recommendation: "HOLD", confidence: 0.79, trend: "NEUTRAL", reasoning: ["Valuation remains stable while near-term growth is moderate.", "The position is suitable for steady income-oriented exposure."] },
-        { symbol: "HDFCBANK.NS", quantity: 12, buy_price: 1680, current_price: 1745, invested_amount: 20160, market_value: 20940, pnl: 780, pnl_percent: 3.87, overall_risk: "MEDIUM", overall_score: 8.1, recommendation: "ACCUMULATE", confidence: 0.84, trend: "BULLISH", reasoning: ["Banking sector momentum is positive with improving breadth.", "The allocation remains within a controlled risk band."] },
+        { symbol: "RELIANCE.NS", quantity: 10, buy_price: 2450, current_price: 2540, invested_amount: 24500, market_value: 25400, pnl: 900, pnl_percent: 3.67, overall_risk: "LOW", overall_score: 8.4, recommendation: "BUY", confidence: 0.88, expected_return: 0.06, predicted_price: 2692.4, trend: "BULLISH", reasoning: ["Momentum remains constructive after a healthy pullback.", "Diversification is strong across sector leaders."] },
+        { symbol: "TCS.NS", quantity: 8, buy_price: 3850, current_price: 3720, invested_amount: 30800, market_value: 29760, pnl: -1040, pnl_percent: -3.38, overall_risk: "LOW", overall_score: 7.8, recommendation: "HOLD", confidence: 0.79, expected_return: 0.03, predicted_price: 3831.6, trend: "NEUTRAL", reasoning: ["Valuation remains stable while near-term growth is moderate.", "The position is suitable for steady income-oriented exposure."] },
+        { symbol: "HDFCBANK.NS", quantity: 12, buy_price: 1680, current_price: 1745, invested_amount: 20160, market_value: 20940, pnl: 780, pnl_percent: 3.87, overall_risk: "MEDIUM", overall_score: 8.1, recommendation: "ACCUMULATE", confidence: 0.84, expected_return: 0.08, predicted_price: 1884.6, trend: "BULLISH", reasoning: ["Banking sector momentum is positive with improving breadth.", "The allocation remains within a controlled risk band."] },
       ];
       const totalInvested = demoHoldings.reduce((sum, h) => sum + (h.invested_amount || 0), 0);
       const totalMarketValue = demoHoldings.reduce((sum, h) => sum + (h.market_value || 0), 0);
@@ -500,9 +531,9 @@ export function PortfolioDoctorPage() {
                 {/* EXPECTED RETURN */}
                 <MetricCard
                   label="EXPECTED RETURN"
-                  value={<><CountUp end={reportData.expectedReturn} decimals={1} duration={1.5} />%</>}
-                  sub="Avg annualised estimate"
-                  tooltip="Average expected return across holdings, derived from LSTM price projections."
+                  value={reportData.expectedReturn == null ? "—" : <><CountUp end={reportData.expectedReturn} decimals={1} duration={1.5} />%</>}
+                  sub="Weighted model estimate"
+                  tooltip="Market-value-weighted expected return from the per-holding model outputs, refreshed against current Yahoo prices where a price target is available."
                   color={
                     reportData.expectedReturn >= 10 ? "var(--success)"
                     : reportData.expectedReturn >= 0 ? "var(--color-teal)"
@@ -513,9 +544,9 @@ export function PortfolioDoctorPage() {
                 {/* EXPECTED VOLATILITY */}
                 <MetricCard
                   label="VOLATILITY"
-                  value={<><CountUp end={reportData.expectedVolatility} decimals={1} duration={1.5} />%</>}
-                  sub="Historical variance"
-                  tooltip="Estimated annualised price volatility. Higher = wider price swings."
+                  value={reportData.expectedVolatility == null ? "—" : <><CountUp end={reportData.expectedVolatility} decimals={1} duration={1.5} />%</>}
+                  sub="Annualized historical volatility"
+                  tooltip="Annualized standard deviation of daily Yahoo Finance portfolio returns. Requires at least three aligned daily observations."
                   color={
                     reportData.expectedVolatility <= 12 ? "var(--success)"
                     : reportData.expectedVolatility <= 20 ? "var(--warning)"
@@ -540,8 +571,8 @@ export function PortfolioDoctorPage() {
                 <MetricCard
                   label="AI CONFIDENCE"
                   value={<><CountUp end={reportData.aiConfidence} duration={1.5} />%</>}
-                  sub="Model agreement"
-                  tooltip="Average calibrated confidence across RF, LSTM, and FinBERT models. Always 0–100%."
+                  sub="Position-weighted confidence"
+                  tooltip="Model confidence averaged across holdings using each holding's current portfolio weight."
                   color={
                     reportData.aiConfidence >= 70 ? "var(--color-teal)"
                     : reportData.aiConfidence >= 50 ? "var(--warning)"

frontend/src/pages/Screener/ScreenerPage.jsx

@@ -126,7 +126,7 @@ export function ScreenerPage() {
     const interval = startLoader();
 
     try {
-      const analysis = await fetchFullStockSignal(symbol);
+      const analysis = await fetchFullStockSignal(symbol, { explainScreener: true });
       stopLoader(interval);
       await new Promise((r) => setTimeout(r, 300)); // let loader reach 100%
 
@@ -193,7 +193,7 @@ export function ScreenerPage() {
       for (const m of matches) {
         const sym = (m.symbol || "").replace(".NS", "");
         try {
-          const analysis = await fetchFullStockSignal(sym);
+          const analysis = await fetchFullStockSignal(sym, { explainScreener: true });
           if (analysis) cards.push(analysis);
         } catch {
           // Match couldn't be fully analysed — skip silently

frontend/src/services/marketService.js

@@ -4,8 +4,11 @@ import { ENDPOINTS } from "../constants/api";
 // Unwrap the v2 success envelope { success, data, ... } -> data
 const unwrapV2 = (response) => response.data?.data ?? response.data;
 
-export const fetchFullStockSignal = async (symbol) => {
-  const response = await apiClient.get(ENDPOINTS.V2_SIGNAL_FULL(symbol), { timeout: 120000 });
+export const fetchFullStockSignal = async (symbol, { explainScreener = false } = {}) => {
+  const response = await apiClient.get(ENDPOINTS.V2_SIGNAL_FULL(symbol), {
+    timeout: 120000,
+    params: explainScreener ? { explain_screener: true } : undefined,
+  });
   return unwrapV2(response);
 };
 

frontend/src/styles/screener.css

@@ -126,3 +126,89 @@
   color: var(--text-secondary);
   border: 1px solid var(--border-subtle);
 }
+
+.sc-explanation {
+  padding: 14px 0;
+  border-top: 1px solid var(--border-subtle);
+  border-bottom: 1px solid var(--border-subtle);
+  color: var(--text-primary);
+}
+
+.sc-explanation-header,
+.sc-explanation-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.sc-explanation-header {
+  justify-content: space-between;
+}
+
+.sc-explanation-title {
+  font-size: 13px;
+  font-weight: 800;
+  color: var(--color-teal);
+}
+
+.sc-explanation-source {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--color-teal);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.sc-explanation-source.is-fallback {
+  color: var(--warning);
+}
+
+.sc-explanation-summary {
+  margin: 10px 0;
+  color: var(--text-primary);
+  font-size: 14px;
+  line-height: 1.55;
+}
+
+.sc-explanation-group {
+  margin-top: 10px;
+}
+
+.sc-explanation-group h4 {
+  margin: 0 0 5px;
+  color: var(--text-secondary);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.sc-explanation-group ul {
+  display: grid;
+  gap: 5px;
+  margin: 0;
+  padding-left: 18px;
+  color: var(--text-secondary);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.sc-explanation-risks li::marker {
+  color: var(--warning);
+}
+
+.sc-explanation-confidence {
+  margin: 10px 0 0;
+  color: var(--text-muted);
+  font-size: 12px;
+  line-height: 1.45;
+}
+
+@media (max-width: 480px) {
+  .sc-explanation-title {
+    font-size: 12px;
+  }
+
+  .sc-explanation-summary {
+    font-size: 13px;
+  }
+}