""" api/main.py =========== Phase 3: Secure FastAPI Backend Endpoints --------- - ``POST /register`` — Hash password via bcrypt, create user profile. - ``POST /login`` — Verify password, return JWT token. - ``POST /analyze`` — (JWT required) Run CNN inference, temporal analysis, and recommendation engine. Returns scores, interventions, attention weights. - ``GET /history`` — (JWT required) Retrieve past analysis sessions. Security -------- - Passwords are NEVER stored in plaintext (bcrypt). - JWT tokens authenticate all ``/analyze`` and ``/history`` requests. - Stress history is encrypted at rest via Fernet (AES-256). Persistence ----------- - User accounts and analysis sessions are stored in a SQLite database. - Sessions survive server restarts and are available upon re-login. """ from __future__ import annotations import hashlib import logging import os import statistics import threading import time from typing import Any, Optional import torch from fastapi import Depends, FastAPI, HTTPException, Query, status from fastapi.middleware.cors import CORSMiddleware from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer from pydantic import BaseModel, Field from database.db import DatabaseManager from database.feedback import FeedbackStore from intervention.engine import RecommendationEngine from intervention.temporal_model import SecureTemporalModel from models.architecture import ( DeBERTaStressClassifier, MiniLMStressClassifier, OptimizedMultichannelCNN, ) from security.auth import ( create_jwt_token, decode_jwt_token, hash_password, verify_password, ) from utils.llm_reward import get_llm_reward from utils.reward import compute_combined_reward from utils.sentiment import compute_sentiment_dampening, get_sentiment_score from utils.text_preprocessing import clean_text from datetime import timedelta # --------------------------------------------------------------------------- # App & global state # --------------------------------------------------------------------------- _APP_START_TIME = time.time() app = FastAPI( title="Stress Detection API", description="Secure, intervention-oriented stress detection system", version="2.0.0", ) # --------------------------------------------------------------------------- # CORS — allow all origins in development / single-server deployments. # For production, restrict ``allow_origins`` to your frontend domain(s). # --------------------------------------------------------------------------- app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) # SQLite-backed user + session store _db = DatabaseManager() # Feedback / experience-replay store (same DB file) _feedback_store = FeedbackStore() # Singletons _recommendation_engine = RecommendationEngine() _temporal_model = SecureTemporalModel() # Security _bearer_scheme = HTTPBearer() # Model (lazy-loaded on first request) _model: Optional[torch.nn.Module] = None _vocab: Optional[Any] = None _model_type: str = "cnn" _decision_threshold: float = 0.5 _tokenizer: Optional[Any] = None _tokenizer_max_length: int = 256 _feature_dim: int = 0 _DEFAULT_VOCAB_SIZE = 10000 _CHECKPOINT_PATH = os.environ.get( "STRESS_MODEL_CHECKPOINT", "checkpoints/model.pt" ) logger = logging.getLogger(__name__) # --------------------------------------------------------------------------- # Inference guardrails # --------------------------------------------------------------------------- # The decision threshold is NEVER allowed to fall below this value, even if # the training checkpoint was produced with a pathologically low threshold # (e.g. 0.15) caused by unconstrained F1-only threshold calibration. _MIN_DECISION_THRESHOLD: float = 0.50 # Clip raw model probabilities to this range before applying the threshold. # Extreme values (< 0.10 or > 0.90) can amplify noise and indicate a # poorly calibrated model; restricting the range keeps decisions sane. _PROB_CLIP_MIN: float = 0.10 _PROB_CLIP_MAX: float = 0.90 # Dead-zone gating: predictions within this distance of the adaptive # threshold are relabelled "uncertain" to avoid committing to a potentially # false high/low near the decision boundary. _CONFIDENCE_DEAD_ZONE: float = 0.07 # Ensemble Monte-Carlo Dropout: number of stochastic forward passes and the # standard-deviation threshold above which the prediction is flagged as # uncertain by the ensemble. _ENSEMBLE_PASSES: int = 3 _ENSEMBLE_UNCERTAINTY_STD: float = 0.08 # Serialises MC-Dropout ensemble passes so concurrent requests do not # interfere with each other's Dropout layer state. _inference_lock: threading.Lock = threading.Lock() def _enable_dropout(m: torch.nn.Module) -> None: """Set only Dropout layers to train mode for MC-Dropout ensemble passes.""" if isinstance(m, torch.nn.Dropout): m.train() def _classify_stress_level(stress_prob: float, decision_threshold: float) -> str: """Map a stress probability to a 4-way human-readable level. Bands (all relative to ``decision_threshold``, default 0.50): ============ ================ ================================ Level Probability range Meaning ============ ================ ================================ low < threshold−0.10 Confidently not stressed uncertain ±0.10 of thresh. Near the boundary; unclear moderate threshold+0.10 … Clearly stressed but manageable threshold+0.25 high ≥ threshold+0.25 High-stress; escalate ============ ================ ================================ """ low_bound = decision_threshold - 0.10 uncertain_upper = decision_threshold + 0.10 high_lower = decision_threshold + 0.25 if stress_prob >= high_lower: return "high" if stress_prob >= uncertain_upper: return "moderate" if stress_prob >= low_bound: return "uncertain" return "low" def _compute_confidence(stress_prob: float, decision_threshold: float) -> float: """Return a confidence score in [0, 1] derived from distance to the threshold. A score of 1.0 means the prediction is maximally far from the boundary (e.g. stress_prob = 0.0 or 1.0 with threshold = 0.5). Values close to 0.0 indicate the prediction is right on the decision boundary. """ dist = abs(stress_prob - decision_threshold) return float(min(dist / _MIN_DECISION_THRESHOLD, 1.0)) # --------------------------------------------------------------------------- # Short-input handler for common single-word inputs # --------------------------------------------------------------------------- _STRESS_WORDS = frozenset([ "tired", "exhausted", "overwhelmed", "burnt", "done", "stressed", "anxious", "depressed", "hopeless", "miserable", ]) _NEUTRAL_WORDS = frozenset([ "fine", "ok", "okay", "good", "alright", ]) # --------------------------------------------------------------------------- # Inference post-processing: signal strength and contrast filtering # --------------------------------------------------------------------------- # High-frequency function words that carry no stress signal on their own. # Used to measure how much *meaningful* content is in the input. _LOW_SIGNAL_WORDS: frozenset[str] = frozenset({ "i", "me", "my", "we", "you", "he", "she", "it", "they", "am", "is", "are", "was", "were", "be", "been", "being", "a", "an", "the", "and", "or", "of", "to", "in", "on", "at", "by", "for", "with", "as", "this", "that", "do", "did", "does", "have", "has", "had", "will", "would", "can", "could", "should", "may", "might", "shall", }) # Contrast conjunctions that signal a positive override following a # stress-trigger phrase (e.g. "I am stressed but happy"). _CONTRAST_CONJUNCTIONS: frozenset[str] = frozenset({ "but", "however", "although", "though", "yet", "despite", "nevertheless", "nonetheless", "whereas", }) def _handle_short_input(text: str) -> float | None: """Return a preset stress probability for very short inputs. Returns ``None`` when the input is not recognised as a common single-word pattern and should be passed to the model instead. """ cleaned = text.lower().strip() if cleaned in _STRESS_WORDS: return 0.8 if cleaned in _NEUTRAL_WORDS: return 0.2 return None def _apply_signal_filter(text: str, stress_prob: float) -> float: """Dampen stress probability when the input lacks meaningful content words. Inputs consisting almost entirely of low-signal function words (e.g. "I am the") carry no semantic content and should not trigger a high stress prediction. Applies a 0.70 dampening factor when fewer than three content words are detected. Parameters ---------- text : str Raw input text. stress_prob : float Current stress probability (after model + sentiment correction). Returns ------- float Dampened stress probability. """ content_words = [ w for w in text.lower().split() if w not in _LOW_SIGNAL_WORDS ] if len(content_words) < 3: stress_prob *= 0.7 return stress_prob def _apply_contrast_filter(text: str, stress_prob: float) -> float: """Dampen stress probability when a contrast conjunction is present. Phrases like "I am stressed *but* happy" or "exhausted *however* grateful" carry a positive override that should suppress the stress score. A 0.80 dampening factor is applied whenever any contrast conjunction is found, regardless of position. Parameters ---------- text : str Raw input text. stress_prob : float Current stress probability. Returns ------- float Dampened stress probability. """ tokens = set(text.lower().split()) if tokens & _CONTRAST_CONJUNCTIONS: stress_prob *= 0.8 return stress_prob def _get_model() -> torch.nn.Module: """Lazy-load or create the CNN model. If a checkpoint file exists at ``_CHECKPOINT_PATH``, the function attempts to load the saved ``model_state_dict``. When the checkpoint was produced by an *older* architecture (e.g. one that used a single ``fc`` layer instead of the current ``attention`` + ``classifier`` head), loading with ``strict=True`` would raise a ``RuntimeError``. To stay backward-compatible the loader: 1. Tries ``strict=True`` first. 2. On key-mismatch ``RuntimeError``, retries with ``strict=False`` so that all *compatible* weights (embedding, conv layers) are restored while new layers keep their random initialisation. 3. Logs every missing / unexpected key for transparency. If no checkpoint exists the model is created with random weights. """ global _model, _decision_threshold, _model_type, _tokenizer, _tokenizer_max_length, _feature_dim if _model is None: checkpoint = None if os.path.isfile(_CHECKPOINT_PATH): try: checkpoint = torch.load( _CHECKPOINT_PATH, map_location="cpu", weights_only=True, ) except Exception as exc: logger.warning( "Failed to read checkpoint %s (%s); using randomly " "initialised weights.", _CHECKPOINT_PATH, exc, ) if isinstance(checkpoint, dict): _model_type = checkpoint.get("model_type", "cnn") threshold = checkpoint.get("decision_threshold") # Backward-compatible: threshold may be serialized as a tensor. if isinstance(threshold, torch.Tensor): threshold = float(threshold.item()) if isinstance(threshold, (float, int)): _decision_threshold = float(threshold) # Safety guard: never use a threshold below the minimum, regardless # of what the checkpoint reports. Unconstrained F1-only calibration # during training can produce pathological values like 0.15. _decision_threshold = max(_decision_threshold, _MIN_DECISION_THRESHOLD) _tokenizer_max_length = int( checkpoint.get("tokenizer_max_length", _tokenizer_max_length) ) _feature_dim = int(checkpoint.get("feature_dim", 0)) feature_columns = checkpoint.get("feature_columns") if _feature_dim == 0 and isinstance(feature_columns, list): _feature_dim = len(feature_columns) dropout = float( checkpoint.get( "dropout", 0.3 if _model_type == "cnn" else 0.1, ) ) else: _model_type = "cnn" dropout = 0.3 _feature_dim = 0 if _model_type == "deberta": _model = DeBERTaStressClassifier(dropout=dropout) elif _model_type == "minilm": _model = MiniLMStressClassifier(dropout=dropout) else: _model = OptimizedMultichannelCNN( vocab_size=_DEFAULT_VOCAB_SIZE, embed_dim=128, num_filters=64, kernel_sizes=(2, 3, 5), num_classes=2, dropout=dropout, aux_dim=_feature_dim, ) if _feature_dim > 0: logger.info( "Checkpoint expects %d auxiliary features; inference " "will use zero-filled features unless provided.", _feature_dim, ) if _model_type in {"deberta", "minilm"}: from transformers import AutoTokenizer model_name = None if isinstance(checkpoint, dict): model_name = checkpoint.get("model_name") if model_name is None: model_name = _model.MODEL_NAME _tokenizer = AutoTokenizer.from_pretrained(model_name) if checkpoint is not None: state_dict = ( checkpoint.get("model_state_dict", checkpoint) if isinstance(checkpoint, dict) else checkpoint ) try: _model.load_state_dict(state_dict, strict=True) logger.info("Loaded checkpoint from %s", _CHECKPOINT_PATH) except RuntimeError as exc: logger.warning( "Strict checkpoint load failed (%s); retrying with " "strict=False to restore compatible weights.", exc, ) result = _model.load_state_dict(state_dict, strict=False) if result.missing_keys: logger.warning( "Missing keys (randomly initialised): %s", result.missing_keys, ) if result.unexpected_keys: logger.warning( "Unexpected keys (ignored): %s", result.unexpected_keys, ) else: logger.info( "No checkpoint found at %s; using randomly initialised " "weights.", _CHECKPOINT_PATH, ) _model.eval() return _model # --------------------------------------------------------------------------- # Pydantic schemas # --------------------------------------------------------------------------- class RegisterRequest(BaseModel): username: str = Field(..., min_length=3, max_length=50) password: str = Field(..., min_length=8) class LoginRequest(BaseModel): username: str password: str remember_me: bool = True class TokenResponse(BaseModel): access_token: str token_type: str = "bearer" class AnalyzeRequest(BaseModel): text: str = Field(..., min_length=1) class InterventionResponse(BaseModel): title: str description: str category: str priority: int class AnalyzeResponse(BaseModel): stress_score: float stress_label: str stress_level: str # "low" | "moderate" | "high" | "uncertain" confidence: float # how far the prediction is from the decision boundary [0, 1] temporal: dict interventions: list[InterventionResponse] is_crisis: bool crisis_message: Optional[str] = None matched_triggers: list[str] attention_weights: list[float] requires_escalation: bool = False # True when 3+ consecutive above-threshold sessions is_uncertain: bool = False # True when ensemble std is high or near-boundary class SessionResponse(BaseModel): """A single past analysis session.""" id: int stress_score: float stress_label: str temporal_data: dict interventions: list[dict] is_crisis: bool crisis_message: Optional[str] = None matched_triggers: list[str] attention_weights: list[float] created_at: float class HistoryResponse(BaseModel): """Paginated list of past analysis sessions.""" sessions: list[SessionResponse] total: int class FeedbackRequest(BaseModel): """User-submitted feedback on a single prediction.""" text: str = Field(..., min_length=1) prediction: float = Field(..., ge=0.0, le=1.0) user_feedback: int = Field(..., ge=0, le=1, description="1 = prediction was correct, 0 = wrong") class FeedbackResponse(BaseModel): """Acknowledgement returned after storing feedback.""" status: str reward: float llm_reward: Optional[int] = None feedback_id: int class FeedbackStatsResponse(BaseModel): """Aggregated feedback statistics for the authenticated user.""" total: int mean_reward: float n_correct: int n_wrong: int accuracy_rate: float class PersonalizationResponse(BaseModel): """Per-user score adjustment derived from their feedback history.""" user_bias: float feedback_count: int description: str # --------------------------------------------------------------------------- # Auth dependency # --------------------------------------------------------------------------- def _get_current_user( credentials: HTTPAuthorizationCredentials = Depends(_bearer_scheme), ) -> str: """Decode the JWT and return the username (``sub`` claim).""" try: payload = decode_jwt_token(credentials.credentials) username: str | None = payload.get("sub") if username is None: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token: missing subject", ) if not _db.user_exists(username): raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="User not found", ) return username except Exception as exc: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail=f"Could not validate credentials: {exc}", ) # --------------------------------------------------------------------------- # Endpoints # --------------------------------------------------------------------------- @app.get("/health") def health() -> dict: """Liveness / readiness probe. Returns the service status, uptime in seconds, and whether the prediction model has been loaded into memory. """ return { "status": "ok", "uptime_seconds": round(time.time() - _APP_START_TIME, 1), "model_loaded": _model is not None, "model_type": _model_type, } @app.get("/model/info") def model_info() -> dict: """Return metadata about the currently loaded prediction model. Useful for the UI settings panel and for debugging. """ return { "model_type": _model_type, "decision_threshold": _decision_threshold, "vocab_size": _DEFAULT_VOCAB_SIZE, "checkpoint_path": _CHECKPOINT_PATH, "checkpoint_exists": os.path.isfile(_CHECKPOINT_PATH), "prob_clip_min": _PROB_CLIP_MIN, "prob_clip_max": _PROB_CLIP_MAX, "feature_dim": _feature_dim, } @app.post("/login", response_model=TokenResponse) def login(req: LoginRequest) -> TokenResponse: """Verify credentials and return a JWT token.""" username_normalized = req.username.strip().lower() logger.info("Login attempt for username: %s", username_normalized) user = _db.get_user(username_normalized) if user is None: logger.warning("Login failed: user '%s' not found in database.", username_normalized) raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid username or password", ) password_match = verify_password(req.password, user["password_hash"]) logger.info("Password match result for '%s': %s", username_normalized, password_match) if not password_match: logger.warning("Login failed: wrong password for user '%s'.", username_normalized) raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid username or password", ) expiry = timedelta(days=7) if req.remember_me else timedelta(hours=1) token = create_jwt_token({"sub": username_normalized}, expires_delta=expiry) logger.info("Token generated successfully for user '%s'.", username_normalized) return TokenResponse(access_token=token) @app.post("/register", response_model=TokenResponse, status_code=201) def register(req: RegisterRequest) -> TokenResponse: """Register a new user with bcrypt-hashed password.""" username_normalized = req.username.strip().lower() if _db.user_exists(username_normalized): raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Username already exists", ) hashed = hash_password(req.password) logger.info("Registering user '%s' with hashed password.", username_normalized) _db.create_user(username_normalized, hashed) token = create_jwt_token({"sub": username_normalized}) return TokenResponse(access_token=token) @app.post("/token/refresh", response_model=TokenResponse) def refresh_token(username: str = Depends(_get_current_user)) -> TokenResponse: """Issue a fresh JWT for the authenticated user.""" token = create_jwt_token({"sub": username}) return TokenResponse(access_token=token) @app.post("/analyze", response_model=AnalyzeResponse) def analyze( req: AnalyzeRequest, username: str = Depends(_get_current_user), ) -> AnalyzeResponse: """Run full stress analysis pipeline (JWT required). Pipeline: 0. Clean and normalise the input text (HTML, URLs, emojis, etc.). 1. Tokenize text and run OptimizedMultichannelCNN inference. 2. Decrypt user's temporal history, update profile, re-encrypt. 3. Run RecommendationEngine. 4. Persist session to database. 5. Return scores, interventions, and attention weights. """ model = _get_model() # ── 0. Text preprocessing ── # Normalise input before any downstream processing so that the text # seen by the model exactly matches what was seen during training. text = clean_text(req.text) if not text: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="Input text is empty after preprocessing.", ) # ── 0b. Short-input shortcut ── short_result = _handle_short_input(text) # ── 1. Model Inference ── attn_weights: list[float] = [] is_uncertain_ensemble: bool = False if short_result is not None: stress_prob = short_result elif _model_type == "cnn": tokens = _simple_tokenize(text) input_tensor = torch.tensor([tokens], dtype=torch.long) # Single eval-mode pass — captures attention weights. with torch.no_grad(): if _feature_dim > 0: # No auxiliary features at inference time; use zero-filled inputs. aux_features = torch.zeros( (1, _feature_dim), dtype=torch.float ) output = model(input_tensor, aux_features=aux_features) else: output = model(input_tensor) logits = output["logits"] attn_weights = output["attention_weights"][0].tolist() p_eval = float(torch.softmax(logits, dim=-1)[0, 1]) # Ensemble MC-Dropout: additional stochastic passes with dropout only. # We selectively set Dropout layers to train mode instead of the whole # model, so the BatchNorm / LayerNorm statistics stay in eval mode. # The lock serialises model-state mutations so concurrent requests # do not interfere with each other's Dropout state. ensemble_probs: list[float] = [p_eval] with _inference_lock: model.apply(_enable_dropout) try: for _ in range(_ENSEMBLE_PASSES - 1): with torch.no_grad(): if _feature_dim > 0: out = model(input_tensor, aux_features=aux_features) else: out = model(input_tensor) ensemble_probs.append( float(torch.softmax(out["logits"], dim=-1)[0, 1]) ) finally: model.eval() stress_prob = statistics.mean(ensemble_probs) ensemble_std = statistics.pstdev(ensemble_probs) is_uncertain_ensemble = ensemble_std > _ENSEMBLE_UNCERTAINTY_STD else: if _tokenizer is None: raise HTTPException( status_code=500, detail="Tokenizer not initialized for transformer model.", ) encoded = _tokenizer( text, return_tensors="pt", truncation=True, max_length=_tokenizer_max_length, ) sentiment_val = get_sentiment_score(text) sentiment_tensor = torch.tensor([sentiment_val], dtype=torch.float) with torch.no_grad(): output = model( input_ids=encoded["input_ids"], attention_mask=encoded.get("attention_mask"), sentiment=sentiment_tensor, ) logits = output["logits"] attn_weights = [] if short_result is None and _model_type != "cnn": # CNN stress_prob is already averaged across ensemble passes above. probs = torch.softmax(logits, dim=-1) stress_prob = float(probs[0, 1]) if short_result is None: # ── Sentiment correction ── dampening = compute_sentiment_dampening(text) stress_prob = stress_prob * dampening # ── Signal-strength filter ── stress_prob = _apply_signal_filter(text, stress_prob) # ── Contrast-phrase filter ── stress_prob = _apply_contrast_filter(text, stress_prob) # ── Probability calibration ── stress_prob = float(min(max(stress_prob, _PROB_CLIP_MIN), _PROB_CLIP_MAX)) stress_label = ( "stress" if stress_prob >= _decision_threshold else "no_stress" ) # ── Multi-level classification + confidence ── stress_level = _classify_stress_level(stress_prob, _decision_threshold) confidence = _compute_confidence(stress_prob, _decision_threshold) # ── 2. Temporal Analysis (decrypt → compute → re-encrypt) ── user_data = _db.get_user(username) analysis, new_encrypted = _temporal_model.process( score=stress_prob, encrypted_history=user_data["encrypted_history"] if user_data else None, ) _db.update_encrypted_history(username, new_encrypted) # ── Dead-zone gating ── # If the probability is within _CONFIDENCE_DEAD_ZONE of the adaptive # threshold, the prediction is too close to the boundary to be reliable. # Override the label to "uncertain" to avoid a false high/low call. if abs(stress_prob - analysis.adaptive_threshold) < _CONFIDENCE_DEAD_ZONE: stress_level = "uncertain" # ── Layer 4: Escalation detection ── # Query the 2 most recent saved sessions (before saving the current one). # If the last 3 sessions (including the current) all exceed the adaptive # threshold, flag the user for escalation to a professional. recent_sessions = _db.get_sessions(username, limit=2, offset=0) past_scores = [s["stress_score"] for s in recent_sessions] all_recent_scores = [stress_prob] + past_scores requires_escalation = ( analysis.score_count >= 3 and len(all_recent_scores) >= 3 and all(s >= analysis.adaptive_threshold for s in all_recent_scores[:3]) ) # ── 3. Recommendation Engine ── recommendation = _recommendation_engine.recommend( text=text, stress_score=stress_prob, is_volatile=analysis.is_volatile, requires_escalation=requires_escalation, ) # ── 4. Build response ── temporal_dict = { "stress_velocity": analysis.stress_velocity, "adaptive_threshold": analysis.adaptive_threshold, "exceeds_threshold": analysis.exceeds_threshold, "is_volatile": analysis.is_volatile, "volatility": analysis.volatility, "score_count": analysis.score_count, } interventions_list = [ { "title": iv.title, "description": iv.description, "category": iv.category, "priority": iv.priority, } for iv in recommendation.interventions ] # ── 5. Persist session to database ── _db.save_session( username=username, stress_score=stress_prob, stress_label=stress_label, temporal_data=temporal_dict, interventions=interventions_list, is_crisis=recommendation.is_crisis, crisis_message=recommendation.crisis_message, matched_triggers=recommendation.matched_triggers, attention_weights=attn_weights, ) return AnalyzeResponse( stress_score=stress_prob, stress_label=stress_label, stress_level=stress_level, confidence=confidence, temporal=temporal_dict, interventions=[ InterventionResponse(**iv) for iv in interventions_list ], is_crisis=recommendation.is_crisis, crisis_message=recommendation.crisis_message, matched_triggers=recommendation.matched_triggers, attention_weights=attn_weights, requires_escalation=requires_escalation, is_uncertain=is_uncertain_ensemble or stress_level == "uncertain", ) @app.get("/history", response_model=HistoryResponse) def history( limit: int = Query(default=50, ge=1, le=200), offset: int = Query(default=0, ge=0), username: str = Depends(_get_current_user), ) -> HistoryResponse: """Retrieve past analysis sessions for the authenticated user. Sessions are returned newest-first and support pagination via ``limit`` and ``offset`` query parameters. """ sessions = _db.get_sessions(username, limit=limit, offset=offset) total = _db.get_session_count(username) return HistoryResponse( sessions=[SessionResponse(**s) for s in sessions], total=total, ) @app.post("/feedback", response_model=FeedbackResponse) def submit_feedback( req: FeedbackRequest, username: str = Depends(_get_current_user), ) -> FeedbackResponse: """Store user feedback on a prediction and compute the RL reward signal. Pipeline -------- 1. Compute a ``±1`` reward from the user's binary rating. 2. Optionally call an LLM judge (if ``OPENAI_API_KEY`` or ``GEMINI_API_KEY`` is set) and average with the user reward. 3. Persist the feedback event and a corrected training sample to the ``feedback`` / ``experience`` tables. 4. Return the reward so the UI can display it to the user. """ llm_r = get_llm_reward(req.text, req.prediction) reward = compute_combined_reward(req.user_feedback, llm_r) feedback_id = _feedback_store.save_feedback( username=username, text=req.text, prediction=req.prediction, user_feedback=req.user_feedback, reward=reward, llm_reward=llm_r, ) return FeedbackResponse( status="saved", reward=reward, llm_reward=llm_r, feedback_id=feedback_id, ) @app.get("/feedback/stats", response_model=FeedbackStatsResponse) def feedback_stats( username: str = Depends(_get_current_user), ) -> FeedbackStatsResponse: """Return aggregated feedback statistics for the authenticated user.""" stats = _feedback_store.get_user_stats(username) return FeedbackStatsResponse(**stats) @app.get("/personalization", response_model=PersonalizationResponse) def personalization( username: str = Depends(_get_current_user), ) -> PersonalizationResponse: """Return a per-user stress-score bias derived from feedback history. The bias is a small additive correction (−0.1 to +0.1) that shifts the model's raw prediction toward what past feedback suggests is accurate for this specific user. A positive bias indicates the model has historically under-predicted stress for this user; a negative bias indicates over-prediction. The correction can be applied at inference time by client code. """ stats = _feedback_store.get_user_stats(username) total = stats["total"] if total == 0: return PersonalizationResponse( user_bias=0.0, feedback_count=0, description="No feedback yet — bias is neutral.", ) # Derive bias: mean_reward of +1 means the model is mostly right (no # correction needed); mean_reward near -1 means it is mostly wrong. # We map [-1, +1] → [+0.1, -0.1]: if the model is wrong more often, # nudge the score up (positive bias) to force the threshold to be met. mean_r = stats["mean_reward"] user_bias = round(-mean_r * 0.1, 4) accuracy_pct = int(stats["accuracy_rate"] * 100) description = ( f"Based on {total} feedback event(s), model accuracy for you is " f"~{accuracy_pct}%. Bias adjustment: {user_bias:+.4f}." ) return PersonalizationResponse( user_bias=user_bias, feedback_count=total, description=description, ) # --------------------------------------------------------------------------- # Helpers # --------------------------------------------------------------------------- _CHUNK_SIZE = 200 def _simple_tokenize(text: str) -> list[int]: """Hash-based tokenization for inference without a stored vocabulary. Maps each whitespace-delimited token to an index in [1, VOCAB_SIZE-1] via ``hashlib.md5`` — a fully deterministic hash that produces the same token IDs on every platform and Python process regardless of ``PYTHONHASHSEED``. Index 0 is reserved for padding. This must stay in sync with ``_tokenize`` in ``training/train.py`` so that a checkpoint trained on Colab loads and infers correctly on Windows (or any other machine). """ tokens = text.lower().split() ids = [ int(hashlib.md5(t.encode("utf-8"), usedforsecurity=False).hexdigest(), 16) % (_DEFAULT_VOCAB_SIZE - 1) + 1 for t in tokens ] # Pad or truncate to CHUNK_SIZE if len(ids) < _CHUNK_SIZE: ids = ids + [0] * (_CHUNK_SIZE - len(ids)) else: ids = ids[:_CHUNK_SIZE] return ids