Update main.py

main.py

@@ -1,744 +1,1956 @@
-import asyncio
-import json
-import os
-import re
-import statistics
-import time
-import uuid
-from dataclasses import dataclass
-from typing import Any, Optional
-import httpx
-from dotenv import load_dotenv
-from fastapi import FastAPI, HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import StreamingResponse
-from pydantic import BaseModel, Field
-
-load_dotenv()
-
-app = FastAPI(title="CortexFlow Backend", version="1.0.0")
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_methods=["GET", "POST"],
-    allow_headers=["*"],
-)
-
-
-GROQ_API_KEY = os.getenv("GROQ_API_KEY", "").strip()
-GROQ_API_BASE = os.getenv("GROQ_API_BASE", "https://api.groq.com/openai/v1").rstrip("/")
-GROQ_TIMEOUT_SECONDS = float(os.getenv("GROQ_TIMEOUT_SECONDS", "40"))
-MODEL_DISCOVERY_TTL_SECONDS = int(os.getenv("MODEL_DISCOVERY_TTL_SECONDS", "900"))
-
-PREFERRED_REASONING_MODELS = [
-    m.strip()
-    for m in os.getenv(
-        "GROQ_REASONING_CANDIDATES",
-        "openai/gpt-oss-120b,llama-3.3-70b-versatile,openai/gpt-oss-20b,llama-3.1-8b-instant",
-    ).split(",")
-    if m.strip()
-]
-PREFERRED_SAFETY_MODELS = [
-    m.strip()
-    for m in os.getenv(
-        "GROQ_SAFETY_CANDIDATES",
-        "openai/gpt-oss-safeguard-20b,openai/gpt-oss-20b,llama-3.1-8b-instant",
-    ).split(",")
-    if m.strip()
-]
-
-OVERRIDE_REASONING_MODEL = os.getenv("GROQ_REASONING_MODEL", "").strip()
-OVERRIDE_SAFETY_MODEL = os.getenv("GROQ_SAFETY_MODEL", "").strip()
-
-MIN_WORDS_REQUIRED = int(os.getenv("MIN_WORDS_REQUIRED", "25"))
-
-STEP_NAMES = [
-    "STT preprocessor",
-    "Lexical agent",
-    "Semantic agent",
-    "Prosody agent",
-    "Syntax agent",
-    "Biomarker mapper",
-    "Report composer",
-]
-DOMAIN_REGION = {
-    "lexical": "Broca's area",
-    "semantic": "Wernicke's area",
-    "prosody": "SMA",
-    "syntax": "DLPFC",
-    "affective": "Amygdala",
-}
-
-STOPWORDS = {
-    "the", "a", "an", "and", "or", "but", "if", "then", "than", "of", "to", "in", "on", "at", "for",
-    "with", "without", "by", "from", "as", "is", "am", "are", "was", "were", "be", "been", "being",
-    "it", "its", "this", "that", "these", "those", "i", "you", "he", "she", "we", "they", "them",
-    "my", "your", "our", "their", "me", "him", "her", "us", "do", "does", "did", "have", "has", "had",
-    "not", "no", "yes", "so", "because", "about", "into", "out", "up", "down", "can", "could", "would",
-    "should", "will", "just", "very", "really", "also",
-}
-
-FILLERS = {
-    "um", "uh", "erm", "hmm", "like", "you", "know", "actually", "basically", "literally", "sort", "kind", "maybe",
-}
-
-POSITIVE_WORDS = {
-    "good", "better", "great", "calm", "confident", "clear", "focused", "stable", "happy", "optimistic", "safe", "steady",
-}
-NEGATIVE_WORDS = {
-    "bad", "worse", "anxious", "scared", "panic", "panicked", "confused", "sad", "depressed", "angry", "overwhelmed", "stressed",
-}
-AROUSAL_WORDS = {
-    "urgent", "immediately", "intense", "extreme", "critical", "afraid", "panic", "terrified", "racing", "shaking", "worried",
-}
-HEDGE_WORDS = {
-    "maybe", "perhaps", "possibly", "probably", "sort", "kind", "might", "could", "guess", "unsure", "not sure",
-}
-SUBORDINATORS = {
-    "because", "although", "though", "while", "unless", "until", "since", "whereas", "however", "therefore", "moreover", "which", "that",
-}
-
-
-class AnalyzeRequest(BaseModel):
-    input_value: Optional[str] = None
-    transcript: Optional[str] = None
-    pause_map: Optional[list[float]] = None
-    audio_duration: Optional[float] = None
-    session_id: Optional[str] = None
-
-
-@dataclass
-class DomainScore:
-    overall: float
-    details: dict[str, float]
-
-@dataclass
-class AnalysisState:
-    scores: dict[str, DomainScore]
-    overall_load: float
-    confidence: float
-    quality_notes: list[str]
-    metrics: dict[str, Any]
-
-
-_MODEL_CACHE: dict[str, Any] = {"updated": 0.0, "models": []}
-_MODEL_CACHE_LOCK = asyncio.Lock()
-
-def clamp01(v: float) -> float:
-    return max(0.0, min(1.0, v))
-
-
-def mean(values: list[float], default: float = 0.0) -> float:
-    return float(statistics.mean(values)) if values else default
-
-
-def tokenize_words(text: str) -> list[str]:
-    return re.findall(r"[A-Za-z']+", text.lower())
-
-
-def split_sentences(text: str) -> list[str]:
-    parts = [p.strip() for p in re.split(r"(?<=[.!?])\s+", text) if p.strip()]
-    return parts if parts else ([text.strip()] if text.strip() else [])
-
-
-def content_words(tokens: list[str]) -> list[str]:
-    return [t for t in tokens if len(t) > 2 and t not in STOPWORDS]
-
-
-def jaccard(a: set[str], b: set[str]) -> float:
-    if not a or not b:
-        return 0.0
-    inter = len(a.intersection(b))
-    union = len(a.union(b))
-    return inter / union if union else 0.0
-
-
-def scale_linear(value: float, low: float, high: float) -> float:
-    if high <= low:
-        return 0.0
-    return clamp01((value - low) / (high - low))
-
-
-def scale_inverse(value: float, good: float, poor: float) -> float:
-    if poor >= good:
-        return 0.0
-    return clamp01((good - value) / (good - poor))
-
-def safe_step_event(name: str, status: str, detail: Optional[str] = None) -> bytes:
-    payload: dict[str, Any] = {"type": "step", "step": {"name": name, "status": status}}
-    if detail:
-        payload["step"]["detail"] = detail
-    return (json.dumps(payload) + "\n").encode()
-
-
-def ensure_nonempty_text(req: AnalyzeRequest) -> str:
-    text = (req.input_value or req.transcript or "").strip()
-    words = tokenize_words(text)
-    if not text:
-        raise HTTPException(status_code=400, detail="No input text provided")
-    if len(words) < MIN_WORDS_REQUIRED:
-        raise HTTPException(
-            status_code=422,
-            detail=f"Need at least {MIN_WORDS_REQUIRED} words for reliable analysis. Received {len(words)} words.",
-        )
-    return text
-
-
-def lexical_domain(tokens: list[str], content: list[str]) -> tuple[DomainScore, dict[str, float]]:
-    total = max(len(tokens), 1)
-    unique = len(set(tokens))
-    filler_hits = sum(1 for t in tokens if t in FILLERS)
-
-    ttr = unique / total
-    density = len(content) / total
-    filler_rate = (filler_hits / total) * 100.0
-
-    s_ttr = clamp01(abs(ttr - 0.52) / 0.30)
-    s_density = clamp01(abs(density - 0.58) / 0.25)
-    s_filler = scale_linear(filler_rate, 2.0, 14.0)
-
-    overall = clamp01((0.4 * s_ttr) + (0.35 * s_density) + (0.25 * s_filler))
-
-    details = {
-        "ttr": round(s_ttr, 4),
-        "density": round(s_density, 4),
-        "filler_rate": round(s_filler, 4),
-    }
-    raw = {
-        "ttr": round(ttr, 4),
-        "lexical_density": round(density, 4),
-        "filler_rate_per_100w": round(filler_rate, 2),
-    }
-    return DomainScore(round(overall, 4), details), raw
-
-
-def semantic_domain(sentences: list[str]) -> tuple[DomainScore, dict[str, float]]:
-    if len(sentences) < 2:
-        coherence = 0.16
-        idea_density = 0.45
-        tangentiality = 0.55
-    else:
-        sentence_content = [set(content_words(tokenize_words(s))) for s in sentences]
-        pairwise = [jaccard(sentence_content[i], sentence_content[i + 1]) for i in range(len(sentence_content) - 1)]
-        coherence = mean(pairwise, default=0.12)
-        avg_content_len = mean([len(x) for x in sentence_content], default=0.0)
-        idea_density = clamp01(avg_content_len / 14.0)
-        tangentiality = clamp01(1.0 - coherence)
-    s_coherence = scale_inverse(coherence, good=0.22, poor=0.05)
-    s_idea_density = scale_inverse(idea_density, good=0.65, poor=0.25)
-    s_tangentiality = scale_linear(tangentiality, low=0.35, high=0.85)
-
-    overall = clamp01((0.45 * s_coherence) + (0.30 * s_idea_density) + (0.25 * s_tangentiality))
-
-    details = {
-        "coherence": round(s_coherence, 4),
-        "idea_density": round(s_idea_density, 4),
-        "tangentiality": round(s_tangentiality, 4),
-    }
-    raw = {
-        "coherence_index": round(coherence, 4),
-        "idea_density_index": round(idea_density, 4),
-        "tangentiality_index": round(tangentiality, 4),
-    }
-    return DomainScore(round(overall, 4), details), raw
-
-
-def prosody_domain(
-    tokens: list[str], text: str, pause_map: Optional[list[float]], audio_duration: Optional[float]
-) -> tuple[DomainScore, dict[str, float], bool]:
-    word_count = max(len(tokens), 1)
-    pauses = [float(p) for p in (pause_map or []) if p >= 0]
-    has_audio_prosody = bool(pauses)
-
-    if audio_duration and audio_duration > 5.0:
-        duration_seconds = audio_duration
-    else:
-        estimated_speech_seconds = word_count / 2.5
-        duration_seconds = estimated_speech_seconds + sum(pauses)
-
-    duration_minutes = max(duration_seconds / 60.0, 0.1)
-    speech_rate = word_count / duration_minutes
-
-    if pauses:
-        pause_freq = len(pauses) / duration_minutes
-        hesitation_ratio = sum(1 for p in pauses if p >= 0.8) / len(pauses)
-    else:
-        punctuation_pauses = len(re.findall(r"[,;:\-]", text))
-        pause_freq = (punctuation_pauses / max(word_count, 1)) * 100
-        hesitation_ratio = sum(1 for t in tokens if t in FILLERS) / max(word_count, 1)
-
-    s_rate = clamp01(abs(speech_rate - 140.0) / 95.0)
-    s_pause = scale_linear(pause_freq, low=8.0, high=30.0)
-    s_hes = scale_linear(hesitation_ratio, low=0.08, high=0.35)
-
-    overall = clamp01((0.4 * s_rate) + (0.35 * s_pause) + (0.25 * s_hes))
-
-    details = {
-        "speech_rate": round(s_rate, 4),
-        "pause_freq": round(s_pause, 4),
-        "hesitation": round(s_hes, 4),
-    }
-    raw = {
-        "speech_rate_wpm": round(speech_rate, 1),
-        "pause_frequency_per_min": round(pause_freq, 2),
-        "hesitation_ratio": round(hesitation_ratio, 4),
-        "duration_seconds": round(duration_seconds, 2),
-    }
-    return DomainScore(round(overall, 4), details), raw, has_audio_prosody
-
-def syntax_domain(tokens: list[str], sentences: list[str], text: str) -> tuple[DomainScore, dict[str, float]]:
-    sentence_count = max(len(sentences), 1)
-    mlu = len(tokens) / sentence_count
-
-    per_sentence_depth = []
-    for s in sentences:
-        stoks = tokenize_words(s)
-        sub_count = sum(1 for t in stoks if t in SUBORDINATORS)
-        comma_count = s.count(",")
-        per_sentence_depth.append(sub_count + (comma_count * 0.5))
-    clause_depth = mean(per_sentence_depth, default=0.0)
-
-    passive_matches = re.findall(r"\b(?:is|are|was|were|be|been|being)\s+\w+(?:ed|en)\b", text.lower())
-    passive_ratio = len(passive_matches) / max(sentence_count, 1)
-
-    s_mlu = clamp01(abs(mlu - 17.0) / 12.0)
-    s_depth = scale_linear(clause_depth, low=2.0, high=6.5)
-    s_passive = scale_linear(passive_ratio, low=0.15, high=1.2)
-
-    overall = clamp01((0.45 * s_mlu) + (0.35 * s_depth) + (0.20 * s_passive))
-
-    details = {
-        "mlu": round(s_mlu, 4),
-        "clause_depth": round(s_depth, 4),
-        "passive_ratio": round(s_passive, 4),
-    }
-    raw = {
-        "mean_length_utterance": round(mlu, 2),
-        "clause_depth_index": round(clause_depth, 2),
-        "passive_ratio": round(passive_ratio, 3),
-    }
-    return DomainScore(round(overall, 4), details), raw
-
-
-def affective_domain(tokens: list[str]) -> tuple[DomainScore, dict[str, float]]:
-    total = max(len(tokens), 1)
-    pos = sum(1 for t in tokens if t in POSITIVE_WORDS)
-    neg = sum(1 for t in tokens if t in NEGATIVE_WORDS)
-    arousal = sum(1 for t in tokens if t in AROUSAL_WORDS)
-    hedge = sum(1 for t in tokens if t in HEDGE_WORDS)
-
-    valence = (pos - neg) / (pos + neg + 1)
-    valence_01 = (valence + 1.0) / 2.0
-    arousal_rate = (arousal / total) * 100.0
-    certainty = 1.0 - clamp01(hedge / max(total * 0.15, 1.0))
-
-    s_valence = scale_inverse(valence_01, good=0.62, poor=0.20)
-    s_arousal = scale_linear(arousal_rate, low=3.0, high=14.0)
-    s_certainty = scale_inverse(certainty, good=0.72, poor=0.32)
-    overall = clamp01((0.4 * s_valence) + (0.35 * s_arousal) + (0.25 * s_certainty))
-
-    details = {
-        "valence": round(s_valence, 4),
-        "arousal": round(s_arousal, 4),
-        "certainty": round(s_certainty, 4),
-    }
-    raw = {
-        "valence_score": round(valence_01, 4),
-        "arousal_rate_per_100w": round(arousal_rate, 2),
-        "certainty_index": round(certainty, 4),
-    }
-    return DomainScore(round(overall, 4), details), raw
-
-
-def compute_confidence(
-    word_count: int, sentence_count: int, has_audio_prosody: bool, repeat_ratio: float
-) -> tuple[float, list[str]]:
-    notes: list[str] = []
-    c_words = clamp01(word_count / 180.0)
-    c_sents = clamp01(sentence_count / 8.0)
-    c_repeat = clamp01(1.0 - (repeat_ratio * 1.4))
-    c_audio = 1.0 if has_audio_prosody else 0.55
-
-    confidence = clamp01((0.45 * c_words) + (0.2 * c_sents) + (0.2 * c_repeat) + (0.15 * c_audio))
-
-    if word_count < 60:
-        notes.append("Low sample length. Interpret results cautiously.")
-    if not has_audio_prosody:
-        notes.append("Prosody is inferred from text patterns because pause-map audio features were not provided.")
-    if repeat_ratio > 0.45:
-        notes.append("High repetition detected, which can reduce semantic reliability.")
-
-    return round(confidence, 4), notes
-
-
-def compute_analysis_state(
-    text: str,
-    pause_map: Optional[list[float]],
-    audio_duration: Optional[float],
-) -> AnalysisState:
-    tokens = tokenize_words(text)
-    sentences = split_sentences(text)
-    cwords = content_words(tokens)
-
-    repeat_ratio = 1.0 - (len(set(tokens)) / max(len(tokens), 1))
-
-    lexical, lexical_raw = lexical_domain(tokens, cwords)
-    semantic, semantic_raw = semantic_domain(sentences)
-    prosody, prosody_raw, has_audio = prosody_domain(tokens, text, pause_map, audio_duration)
-    syntax, syntax_raw = syntax_domain(tokens, sentences, text)
-    affective, affective_raw = affective_domain(tokens)
-    confidence, quality_notes = compute_confidence(
-        word_count=len(tokens),
-        sentence_count=len(sentences),
-        has_audio_prosody=has_audio,
-        repeat_ratio=repeat_ratio,
-    )
-
-    scores = {
-        "lexical": lexical,
-        "semantic": semantic,
-        "prosody": prosody,
-        "syntax": syntax,
-        "affective": affective,
-    }
-
-    weighted = (
-        (0.22 * lexical.overall)
-        + (0.23 * semantic.overall)
-        + (0.18 * prosody.overall)
-        + (0.22 * syntax.overall)
-        + (0.15 * affective.overall)
-    )
-
-    confidence_factor = 0.75 + (0.25 * confidence)
-    overall_load = clamp01(weighted * confidence_factor)
-
-    metrics = {
-        "word_count": len(tokens),
-        "sentence_count": len(sentences),
-        "repeat_ratio": round(repeat_ratio, 4),
-        "lexical": lexical_raw,
-        "semantic": semantic_raw,
-        "prosody": prosody_raw,
-        "syntax": syntax_raw,
-        "affective": affective_raw,
-    }
-
-    return AnalysisState(
-        scores=scores,
-        overall_load=round(overall_load, 4),
-        confidence=confidence,
-        quality_notes=quality_notes,
-        metrics=metrics,
-    )
-
-
-def severity_from_score(value: float) -> str:
-    if value >= 0.72:
-        return "high"
-    if value >= 0.42:
-        return "moderate"
-    return "low"
-
-def level_from_overall(overall_load: float, confidence: float) -> str:
-    if overall_load >= 0.68:
-        base = "high"
-    elif overall_load >= 0.44:
-        base = "moderate"
-    else:
-        base = "low"
-
-    if confidence < 0.45 and base == "high":
-        return "moderate"
-    return base
-
-
-def summary_fallback(state: AnalysisState, risk_level: str) -> str:
-    top_domain = max(state.scores.items(), key=lambda kv: kv[1].overall)[0]
-    top_value = state.scores[top_domain].overall
-    confidence_pct = round(state.confidence * 100)
-    return (
-        f"This analysis found a {risk_level} overall cognitive load signal based on linguistic and timing features. "
-        f"The strongest deviation appeared in {top_domain} markers (score {top_value:.2f}). "
-        f"Confidence is {confidence_pct}% and this output is screening support only, not a diagnosis."
-    )
-
-
-def make_highlights(state: AnalysisState) -> list[dict[str, Any]]:
-    sorted_domains = sorted(state.scores.items(), key=lambda kv: kv[1].overall, reverse=True)
-    highlights: list[dict[str, Any]] = []
-    for domain, score in sorted_domains[:3]:
-        if score.overall >= 0.66:
-            finding = "Elevated deviation from expected baseline in this domain."
-        elif score.overall >= 0.42:
-            finding = "Mild-to-moderate deviation with mixed stability."
-        else:
-            finding = "Signals remain within expected variation for this domain."
-
-        highlights.append(
-            {
-                "region": DOMAIN_REGION[domain],
-                "activation": round(score.overall, 4),
-                "finding": finding,
-                "clinical_context": "Screening signal only. Interpret alongside clinical judgement and repeated assessments.",
-            }
-        )
-    return highlights
-
-
-def make_indicators(state: AnalysisState) -> list[dict[str, Any]]:
-    indicators: list[dict[str, Any]] = []
-    for domain, dscore in state.scores.items():
-        for k, v in dscore.details.items():
-            if v < 0.42:
-                continue
-            indicators.append(
-                {
-                    "indicator": f"{domain.title()} · {k.replace('_', ' ').title()}",
-                    "severity": severity_from_score(v),
-                    "explanation": f"Computed score {v:.2f} from measured input features; higher means greater deviation from baseline patterns.",
-                }
-            )
-    indicators.sort(key=lambda x: {"high": 2, "moderate": 1, "low": 0}[x["severity"]], reverse=True)
-    return indicators[:6]
-
-
-def recommendation_for_level(level: str, confidence: float) -> str:
-    if level == "high":
-        return (
-            "Repeat this assessment with a longer sample, then discuss the combined results with a qualified clinician. "
-            "Do not treat this result as a diagnosis."
-        )
-    if level == "moderate":
-        return (
-            "Collect 1-2 additional samples across different times of day to confirm trend stability before drawing conclusions."
-        )
-    if confidence < 0.5:
-        return "Provide a longer speech sample for stronger reliability before interpreting the result."
-    return "Current signals are relatively stable. Continue periodic monitoring rather than one-off interpretation."
-
-
-async def fetch_available_models() -> list[str]:
-    if not GROQ_API_KEY:
-        return []
-
-    async with _MODEL_CACHE_LOCK:
-        now = time.time()
-        if now - float(_MODEL_CACHE["updated"]) < MODEL_DISCOVERY_TTL_SECONDS:
-            return list(_MODEL_CACHE["models"])
-
-        headers = {"Authorization": f"Bearer {GROQ_API_KEY}"}
-        try:
-            async with httpx.AsyncClient(timeout=GROQ_TIMEOUT_SECONDS) as client:
-                res = await client.get(f"{GROQ_API_BASE}/models", headers=headers)
-                res.raise_for_status()
-                data = res.json().get("data", [])
-                models = sorted({item.get("id", "") for item in data if item.get("id")})
-                _MODEL_CACHE["updated"] = now
-                _MODEL_CACHE["models"] = models
-                return models
-        except Exception:
-            return list(_MODEL_CACHE["models"])
-
-
-def pick_model(available: list[str], override: str, candidates: list[str]) -> Optional[str]:
-    if override and override in available:
-        return override
-
-    for m in candidates:
-        if m in available:
-            return m
-    for m in available:
-        lowered = m.lower()
-        if "instruct" in lowered or "versatile" in lowered or "gpt-oss" in lowered:
-            return m
-
-    return available[0] if available else None
-
-
-async def groq_chat(model: str, system: str, user: str, temperature: float = 0.2) -> Optional[str]:
-    if not GROQ_API_KEY or not model:
-        return None
-
-    headers = {
-        "Authorization": f"Bearer {GROQ_API_KEY}",
-        "Content-Type": "application/json",
-    }
-    payload = {
-        "model": model,
-        "temperature": temperature,
-        "messages": [
-            {"role": "system", "content": system},
-            {"role": "user", "content": user},
-        ],
-    }
-
-    try:
-        async with httpx.AsyncClient(timeout=GROQ_TIMEOUT_SECONDS) as client:
-            res = await client.post(f"{GROQ_API_BASE}/chat/completions", headers=headers, json=payload)
-            res.raise_for_status()
-            data = res.json()
-            return data["choices"][0]["message"]["content"].strip()
-    except Exception:
-        return None
-
-
-async def compose_safe_summary(state: AnalysisState, risk_level: str) -> tuple[str, dict[str, Optional[str]]]:
-    available = await fetch_available_models()
-    reasoning_model = pick_model(available, OVERRIDE_REASONING_MODEL, PREFERRED_REASONING_MODELS)
-    safety_model = pick_model(available, OVERRIDE_SAFETY_MODEL, PREFERRED_SAFETY_MODELS)
-
-    model_meta = {
-        "reasoning_model": reasoning_model,
-        "safety_model": safety_model,
-    }
-
-    baseline_summary = summary_fallback(state, risk_level)
-    if not reasoning_model:
-        return baseline_summary, model_meta
-
-    features_for_prompt = {
-        "risk_level": risk_level,
-        "overall_cognitive_load": state.overall_load,
-        "confidence": state.confidence,
-        "scores": {k: v.overall for k, v in state.scores.items()},
-        "quality_notes": state.quality_notes,
-        "metrics": state.metrics,
-    }
-    system = (
-        "You summarize computational language-screening outputs. "
-        "Never diagnose disease, never use alarming wording, and always state uncertainty when confidence is limited. "
-        "Output exactly 2-3 sentences in plain text."
-    )
-    user = "Write a careful summary for this analysis:\n" + json.dumps(features_for_prompt)
-
-    summary = await groq_chat(reasoning_model, system, user, temperature=0.15)
-    if not summary:
-        return baseline_summary, model_meta
-
-    if safety_model:
-        safety_system = (
-            "You are a safety editor for health-adjacent UX. "
-            "Rewrite text to avoid panic, avoid diagnosis claims, and keep uncertainty explicit. "
-            "Keep 2-3 sentences."
-        )
-        safety_user = (
-            "Rewrite this summary to be non-alarmist and clinically careful while keeping factual content:\n"
-            + summary
-            + "\n\nConfidence: "
-            + str(state.confidence)
-        )
-        safe = await groq_chat(safety_model, safety_system, safety_user, temperature=0.1)
-        if safe:
-            summary = safe
-
-    return summary, model_meta
-
-
-@app.get("/health")
-async def health() -> dict[str, Any]:
-    available = await fetch_available_models()
-    return {
-        "ok": True,
-        "service": "cortexflow-backend",
-        "groq_configured": bool(GROQ_API_KEY),
-        "model_count": len(available),
-    }
-
-
-@app.get("/models/recommended")
-async def models_recommended() -> dict[str, Any]:
-    available = await fetch_available_models()
-    return {
-        "available_models": available,
-        "recommended": {
-            "reasoning": pick_model(available, OVERRIDE_REASONING_MODEL, PREFERRED_REASONING_MODELS),
-            "safety": pick_model(available, OVERRIDE_SAFETY_MODEL, PREFERRED_SAFETY_MODELS),
-            "transcription": "whisper-large-v3-turbo",
-        },
-        "notes": {
-            "production_primary": "openai/gpt-oss-120b",
-            "production_fallback": "llama-3.3-70b-versatile",
-            "fast_fallback": "openai/gpt-oss-20b",
-        },
-    }
-
-@app.post("/analyze")
-async def analyze(req: AnalyzeRequest):
-    text = ensure_nonempty_text(req)
-    session_id = req.session_id or str(uuid.uuid4())
-
-    async def generate():
-        for idx, step_name in enumerate(STEP_NAMES):
-            yield safe_step_event(step_name, "running" if idx == 0 else "pending")
-
-        try:
-            state = compute_analysis_state(text, req.pause_map, req.audio_duration)
-            yield safe_step_event("STT preprocessor", "done", "Input normalized and validated")
-            yield safe_step_event("Lexical agent", "running")
-
-            await asyncio.sleep(0)
-            yield safe_step_event("Lexical agent", "done")
-            yield safe_step_event("Semantic agent", "running")
-
-            await asyncio.sleep(0)
-            yield safe_step_event("Semantic agent", "done")
-            yield safe_step_event("Prosody agent", "running")
-
-            await asyncio.sleep(0)
-            yield safe_step_event("Prosody agent", "done")
-            yield safe_step_event("Syntax agent", "running")
-
-            await asyncio.sleep(0)
-            yield safe_step_event("Syntax agent", "done")
-            yield safe_step_event("Biomarker mapper", "running")
-
-            scores_payload = {
-                domain: {**score.details, "overall": score.overall}
-                for domain, score in state.scores.items()
-            }
-
-            yield safe_step_event("Biomarker mapper", "done")
-            yield safe_step_event("Report composer", "running")
-
-            risk_level = level_from_overall(state.overall_load, state.confidence)
-            summary, model_meta = await compose_safe_summary(state, risk_level)
-
-            report = {
-                "summary": summary,
-                "risk_level": risk_level,
-                "overall_cognitive_load": state.overall_load,
-                "highlights": make_highlights(state),
-                "risk_indicators": make_indicators(state),
-                "recommendation": recommendation_for_level(risk_level, state.confidence),
-                "disclaimer": (
-                    "This tool is a non-diagnostic screening aid. It can be wrong and must not be used as a standalone "
-                    "medical decision system. If you are concerned, consult a qualified clinician."
-                ),
-                "quality": {
-                    "confidence": state.confidence,
-                    "notes": state.quality_notes,
-                },
-                "model_info": model_meta,
-            }
-            yield safe_step_event("Report composer", "done")
-
-            payload = {
-                "type": "end",
-                "message": summary,
-                "scores": scores_payload,
-                "report": report,
-                "session_id": session_id,
-            }
-            yield (json.dumps(payload) + "\n").encode()
-
-        except HTTPException as exc:
-            yield (json.dumps({"type": "error", "message": exc.detail}) + "\n").encode()
-        except Exception as exc:
-            yield (json.dumps({"type": "error", "message": f"Analysis failed: {str(exc)}"}) + "\n").encode()
-
-    return StreamingResponse(
-        generate(),
-        media_type="text/plain",
-        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
-    )
+import asyncio
+import json
+import os
+import re
+import statistics
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional
+import httpx
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+
+
+load_dotenv()
+app = FastAPI(title="CortexFlow Backend", version="1.0.0")
+
+app.add_middleware(
+
+    CORSMiddleware,
+
+    allow_origins=["*"],
+
+    allow_methods=["GET", "POST"],
+
+    allow_headers=["*"],
+
+)
+
+
+
+
+
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "").strip()
+GROQ_API_BASE = os.getenv("GROQ_API_BASE", "https://api.groq.com/openai/v1").rstrip("/")
+GROQ_TIMEOUT_SECONDS = float(os.getenv("GROQ_TIMEOUT_SECONDS", "40"))
+MODEL_DISCOVERY_TTL_SECONDS = int(os.getenv("MODEL_DISCOVERY_TTL_SECONDS", "900"))
+
+
+
+PREFERRED_REASONING_MODELS = [
+
+    m.strip()
+
+    for m in os.getenv(
+
+        "GROQ_REASONING_CANDIDATES",
+
+        "openai/gpt-oss-120b,llama-3.3-70b-versatile,openai/gpt-oss-20b,llama-3.1-8b-instant",
+
+    ).split(",")
+
+    if m.strip()
+
+]
+
+PREFERRED_SAFETY_MODELS = [
+
+    m.strip()
+
+    for m in os.getenv(
+
+        "GROQ_SAFETY_CANDIDATES",
+
+        "openai/gpt-oss-safeguard-20b,openai/gpt-oss-20b,llama-3.1-8b-instant",
+
+    ).split(",")
+
+    if m.strip()
+
+]
+
+
+
+OVERRIDE_REASONING_MODEL = os.getenv("GROQ_REASONING_MODEL", "").strip()
+OVERRIDE_SAFETY_MODEL = os.getenv("GROQ_SAFETY_MODEL", "").strip()
+GROQ_TRANSCRIBE_MODEL = os.getenv("GROQ_TRANSCRIBE_MODEL", "whisper-large-v3-turbo").strip() or "whisper-large-v3-turbo"
+
+MIN_WORDS_REQUIRED = int(os.getenv("MIN_WORDS_REQUIRED", "25"))
+
+
+
+STEP_NAMES = [
+
+    "STT preprocessor",
+
+    "Lexical agent",
+
+    "Semantic agent",
+
+    "Prosody agent",
+
+    "Syntax agent",
+
+    "Biomarker mapper",
+
+    "Report composer",
+
+]
+
+DOMAIN_REGION = {
+
+    "lexical": "Broca's area",
+
+    "semantic": "Wernicke's area",
+
+    "prosody": "SMA",
+
+    "syntax": "DLPFC",
+
+    "affective": "Amygdala",
+
+}
+
+
+
+STOPWORDS = {
+
+    "the", "a", "an", "and", "or", "but", "if", "then", "than", "of", "to", "in", "on", "at", "for",
+
+    "with", "without", "by", "from", "as", "is", "am", "are", "was", "were", "be", "been", "being",
+
+    "it", "its", "this", "that", "these", "those", "i", "you", "he", "she", "we", "they", "them",
+
+    "my", "your", "our", "their", "me", "him", "her", "us", "do", "does", "did", "have", "has", "had",
+
+    "not", "no", "yes", "so", "because", "about", "into", "out", "up", "down", "can", "could", "would",
+
+    "should", "will", "just", "very", "really", "also",
+    # Common Romanized Hindi stopwords for code-mixed speech.
+    "hai", "hain", "tha", "thi", "the", "ho", "hoga", "hogi", "honge", "main", "mein", "mera", "meri", "mere",
+    "hum", "tum", "aap", "ye", "yeh", "wo", "woh", "is", "iss", "us", "uss", "ko", "se", "ka", "ki", "ke",
+    "par", "aur", "lekin", "magar", "kyunki", "kyonki", "agar", "jab", "tab", "tak", "ya", "nahi", "nahin", "haan",
+    # Common Devanagari stopwords for native Hindi transcripts.
+    "है", "हैं", "था", "थी", "थे", "हो", "होगा", "होगी", "होंगे", "मैं", "में", "मेरा", "मेरी", "मेरे", "हम",
+    "तुम", "आप", "ये", "यह", "वो", "वह", "इस", "उस", "को", "से", "का", "की", "के", "पर", "और", "लेकिन",
+    "मगर", "क्योंकि", "अगर", "जब", "तब", "तक", "या", "नहीं", "हाँ",
+
+}
+
+
+
+FILLERS = {
+
+    "um", "uh", "erm", "hmm", "like", "actually", "basically", "literally",
+    "matlab", "achha", "accha", "toh", "na", "yaar", "dekho", "samjho", "मतलब", "अच्छा", "तो", "ना",
+
+}
+
+
+
+POSITIVE_WORDS = {
+
+    "good", "better", "great", "calm", "confident", "clear", "focused", "stable", "happy", "optimistic", "safe", "steady",
+    "accha", "badhiya", "shaant", "khush", "सुरक्षित", "शांत", "खुश", "अच्छा",
+
+}
+
+NEGATIVE_WORDS = {
+
+    "bad", "worse", "anxious", "scared", "panic", "panicked", "confused", "sad", "depressed", "angry", "overwhelmed", "stressed",
+    "bura", "ghabrahat", "darr", "pareshan", "dukhi", "चिंतित", "डरा", "उलझन", "दुखी", "तनाव",
+
+}
+
+AROUSAL_WORDS = {
+
+    "urgent", "immediately", "intense", "extreme", "critical", "afraid", "panic", "terrified", "racing", "shaking", "worried",
+    "jaldi", "turant", "tez", "bahut", "घबराहट", "तुरंत", "जल्दी", "तेज", "चिंता",
+
+}
+
+HEDGE_WORDS = {
+
+    "maybe", "perhaps", "possibly", "probably", "sort", "kind", "might", "could", "guess", "unsure", "not sure",
+    "shayad", "lagta", "shayad", "pata", "कदाचित", "शायद", "लगता", "पता",
+
+}
+
+FILLER_PHRASES = {
+    "you know",
+    "i mean",
+    "sort of",
+    "kind of",
+    "pata hai",
+    "you know what",
+}
+
+HEDGE_PHRASES = {
+    "not sure",
+    "i guess",
+    "sort of",
+    "kind of",
+    "pata nahi",
+    "mujhe lagta",
+}
+
+SUBORDINATORS = {
+
+    "because", "although", "though", "while", "unless", "until", "since", "whereas", "however", "therefore", "moreover", "which", "that",
+    "kyunki", "kyonki", "agar", "jab", "jabki", "lekin", "magar", "isliye", "jo", "कि", "क्योंकि", "अगर", "जब", "जबकि", "लेकिन", "मगर", "इसलिए", "जो",
+
+}
+
+ROMAN_HINDI_MARKERS = {
+    "hai", "hain", "tha", "thi", "the", "main", "mein", "mera", "meri", "mere", "hum", "tum", "aap", "ye", "yeh",
+    "wo", "woh", "ko", "se", "ka", "ki", "ke", "par", "aur", "lekin", "magar", "kyunki", "kyonki", "agar", "jab",
+    "tab", "tak", "ya", "nahi", "nahin", "haan", "accha", "achha", "matlab", "yaar", "jaldi", "turant", "shayad",
+    "pata", "samjho", "dekho", "bahut", "thoda", "zyada", "abhi", "kal", "kar", "karna", "kiya", "karo", "raha", "rahi",
+}
+
+
+
+
+
+class AnalyzeRequest(BaseModel):
+
+    input_value: Optional[str] = None
+
+    transcript: Optional[str] = None
+
+    pause_map: Optional[list[float]] = None
+
+    audio_duration: Optional[float] = None
+
+    detected_language: Optional[str] = None
+
+    language_profile: Optional[dict[str, Any]] = None
+
+    session_id: Optional[str] = None
+
+
+
+
+
+@dataclass
+
+class DomainScore:
+
+    overall: float
+
+    details: dict[str, float]
+
+
+
+@dataclass
+
+class AnalysisState:
+
+    scores: dict[str, DomainScore]
+
+    overall_load: float
+
+    confidence: float
+
+    quality_notes: list[str]
+
+    language_profile: dict[str, Any]
+
+    metrics: dict[str, Any]
+
+
+
+
+
+_MODEL_CACHE: dict[str, Any] = {"updated": 0.0, "models": []}
+
+_MODEL_CACHE_LOCK = asyncio.Lock()
+
+LATIN_TOKEN_RE = re.compile(r"[A-Za-z]+(?:'[A-Za-z]+)?")
+DEVANAGARI_TOKEN_RE = re.compile(r"[\u0900-\u097F]+")
+WORD_TOKEN_RE = re.compile(r"[A-Za-z]+(?:'[A-Za-z]+)?|[\u0900-\u097F]+")
+
+
+
+def clamp01(v: float) -> float:
+
+    return max(0.0, min(1.0, v))
+
+
+
+
+
+def mean(values: list[float], default: float = 0.0) -> float:
+
+    return float(statistics.mean(values)) if values else default
+
+
+
+
+
+def tokenize_words(text: str) -> list[str]:
+
+    return [tok.lower() for tok in WORD_TOKEN_RE.findall(text)]
+
+
+
+
+
+def split_sentences(text: str) -> list[str]:
+
+    parts = [p.strip() for p in re.split(r"(?<=[.!?।])\s+", text) if p.strip()]
+
+    return parts if parts else ([text.strip()] if text.strip() else [])
+
+
+
+
+
+def content_words(tokens: list[str]) -> list[str]:
+
+    return [t for t in tokens if len(t) > 2 and t not in STOPWORDS]
+
+
+def read_profile_ratio(profile: Optional[dict[str, Any]], snake_key: str, camel_key: str) -> Optional[float]:
+
+    if not profile or not isinstance(profile, dict):
+
+        return None
+
+    raw = profile.get(snake_key)
+
+    if raw is None:
+
+        raw = profile.get(camel_key)
+
+    if raw is None:
+
+        return None
+
+    try:
+
+        return clamp01(float(raw))
+
+    except (TypeError, ValueError):
+
+        return None
+
+
+def detect_language_profile(
+
+    text: str,
+
+    hinted_language: Optional[str] = None,
+
+    hinted_profile: Optional[dict[str, Any]] = None,
+
+) -> dict[str, Any]:
+
+    latin_tokens = [tok.lower() for tok in LATIN_TOKEN_RE.findall(text)]
+
+    devanagari_tokens = DEVANAGARI_TOKEN_RE.findall(text)
+
+    roman_hindi_hits = sum(1 for tok in latin_tokens if tok in ROMAN_HINDI_MARKERS)
+
+    hindi_tokens = len(devanagari_tokens) + roman_hindi_hits
+
+    english_tokens = max(len(latin_tokens) - roman_hindi_hits, 0)
+
+    total = max(hindi_tokens + english_tokens, 1)
+
+
+
+    hindi_ratio = hindi_tokens / total
+
+    english_ratio = english_tokens / total
+
+    devanagari_ratio = len(devanagari_tokens) / total
+
+
+
+    hinted_english_ratio = read_profile_ratio(hinted_profile, "english_ratio", "englishRatio")
+
+    hinted_hindi_ratio = read_profile_ratio(hinted_profile, "hindi_ratio", "hindiRatio")
+
+    if hinted_english_ratio is not None and hinted_hindi_ratio is not None and (hinted_english_ratio + hinted_hindi_ratio) > 0:
+
+        hinted_total = hinted_english_ratio + hinted_hindi_ratio
+
+        hinted_english_ratio /= hinted_total
+
+        hinted_hindi_ratio /= hinted_total
+
+        english_ratio = (0.75 * english_ratio) + (0.25 * hinted_english_ratio)
+
+        hindi_ratio = (0.75 * hindi_ratio) + (0.25 * hinted_hindi_ratio)
+
+        ratio_total = max(english_ratio + hindi_ratio, 1e-6)
+
+        english_ratio = english_ratio / ratio_total
+
+        hindi_ratio = hindi_ratio / ratio_total
+
+
+
+    label = "multilingual"
+
+    if hindi_ratio >= 0.2 and english_ratio >= 0.2:
+
+        label = "hinglish"
+
+    elif hindi_ratio >= 0.68:
+
+        label = "hindi"
+
+    elif english_ratio >= 0.68:
+
+        label = "english"
+
+
+
+    hint = (hinted_language or "").strip().lower()
+
+    if hint in {"hi", "hindi"}:
+
+        if english_ratio >= 0.2:
+
+            label = "hinglish"
+
+        elif label == "multilingual":
+
+            label = "hindi"
+
+    elif hint in {"en", "english"}:
+
+        if hindi_ratio >= 0.2:
+
+            label = "hinglish"
+
+        elif label == "multilingual":
+
+            label = "english"
+
+
+
+    if hinted_profile and isinstance(hinted_profile, dict):
+
+        hinted_label = str(hinted_profile.get("label", "")).strip().lower()
+
+        if hinted_label in {"hinglish", "hindi", "english", "multilingual"} and (
+
+            label == "multilingual" or abs(hindi_ratio - english_ratio) < 0.12
+
+        ):
+
+            label = hinted_label
+
+
+
+    return {
+
+        "label": label,
+
+        "english_ratio": round(english_ratio, 4),
+
+        "hindi_ratio": round(hindi_ratio, 4),
+
+        "devanagari_ratio": round(devanagari_ratio, 4),
+
+    }
+
+
+
+
+
+def jaccard(a: set[str], b: set[str]) -> float:
+
+    if not a or not b:
+
+        return 0.0
+
+    inter = len(a.intersection(b))
+
+    union = len(a.union(b))
+
+    return inter / union if union else 0.0
+
+
+
+
+
+def scale_linear(value: float, low: float, high: float) -> float:
+
+    if high <= low:
+
+        return 0.0
+
+    return clamp01((value - low) / (high - low))
+
+
+
+
+
+def scale_inverse(value: float, good: float, poor: float) -> float:
+
+    if poor >= good:
+
+        return 0.0
+
+    return clamp01((good - value) / (good - poor))
+
+
+def pick_language_target(
+
+    language_profile: dict[str, Any],
+
+    english: float,
+
+    hinglish: float,
+
+    hindi: float,
+
+    multilingual: Optional[float] = None,
+
+) -> float:
+
+    try:
+
+        english_ratio = clamp01(float(language_profile.get("english_ratio", 0.0)))
+
+    except (TypeError, ValueError):
+
+        english_ratio = 0.0
+
+    try:
+
+        hindi_ratio = clamp01(float(language_profile.get("hindi_ratio", 0.0)))
+
+    except (TypeError, ValueError):
+
+        hindi_ratio = 0.0
+
+    ratio_total = english_ratio + hindi_ratio
+
+
+
+    if ratio_total > 1e-6:
+
+        english_weight = english_ratio / ratio_total
+
+        hindi_weight = hindi_ratio / ratio_total
+
+        base_target = (english_weight * english) + (hindi_weight * hindi)
+
+        code_mix_strength = clamp01(2.0 * min(english_weight, hindi_weight))
+
+        blended_target = ((1.0 - code_mix_strength) * base_target) + (code_mix_strength * hinglish)
+
+        if multilingual is not None:
+
+            blended_target = (0.9 * blended_target) + (0.1 * multilingual)
+
+        return blended_target
+
+
+
+    label = str(language_profile.get("label", "english")).lower()
+
+    if label == "hinglish":
+
+        return hinglish
+
+    if label == "hindi":
+
+        return hindi
+
+    if label == "multilingual":
+
+        return multilingual if multilingual is not None else (english + hindi) / 2.0
+
+    return english
+
+
+def transcription_model_capabilities(model_name: str) -> dict[str, Any]:
+
+    normalized = model_name.strip().lower()
+
+    if not normalized:
+
+        return {
+
+            "model": "unknown",
+
+            "multilingual": False,
+
+            "hindi_supported": False,
+
+            "hinglish_supported": False,
+
+            "notes": "No transcription model configured.",
+
+        }
+
+
+
+    english_only = normalized.endswith("-en") or normalized in {
+
+        "distil-whisper-large-v3-en",
+
+        "whisper-large-v3-en",
+
+    }
+
+    multilingual = (
+
+        ("whisper" in normalized and not english_only)
+
+        or ("gpt-4o-mini-transcribe" in normalized)
+
+        or ("gpt-4o-transcribe" in normalized)
+
+    )
+
+
+
+    if english_only:
+
+        notes = "Configured model appears English-only. Use a multilingual Whisper model for Hindi/Hinglish."
+
+    elif multilingual:
+
+        notes = "Configured model supports multilingual transcription, including Hindi and code-mixed Hinglish."
+
+    else:
+
+        notes = "Model capability is unknown; verify multilingual Hindi support in provider documentation."
+
+
+
+    return {
+
+        "model": model_name,
+
+        "multilingual": multilingual,
+
+        "hindi_supported": multilingual,
+
+        "hinglish_supported": multilingual,
+
+        "notes": notes,
+
+    }
+
+
+
+def safe_step_event(name: str, status: str, detail: Optional[str] = None) -> bytes:
+
+    payload: dict[str, Any] = {"type": "step", "step": {"name": name, "status": status}}
+
+    if detail:
+
+        payload["step"]["detail"] = detail
+
+    return (json.dumps(payload) + "\n").encode()
+
+
+def count_phrase_hits(text: str, phrases: set[str]) -> int:
+
+    lowered = text.lower()
+
+    return sum(lowered.count(phrase) for phrase in phrases if phrase)
+
+
+def estimate_filler_hits(tokens: list[str], text: str) -> int:
+
+    token_hits = sum(1 for t in tokens if t in FILLERS)
+
+    phrase_hits = count_phrase_hits(text, FILLER_PHRASES)
+
+    return token_hits + phrase_hits
+
+
+def estimate_hedge_hits(tokens: list[str], text: str) -> int:
+
+    token_hits = sum(1 for t in tokens if t in HEDGE_WORDS)
+
+    phrase_hits = count_phrase_hits(text, HEDGE_PHRASES)
+
+    return token_hits + phrase_hits
+
+
+
+
+
+def ensure_nonempty_text(req: AnalyzeRequest) -> str:
+
+    text = (req.input_value or req.transcript or "").strip()
+
+    words = tokenize_words(text)
+
+    if not text:
+
+        raise HTTPException(status_code=400, detail="No input text provided")
+
+    if len(words) < MIN_WORDS_REQUIRED:
+
+        raise HTTPException(
+
+            status_code=422,
+
+            detail=f"Need at least {MIN_WORDS_REQUIRED} words for reliable analysis. Received {len(words)} words.",
+
+        )
+
+    return text
+
+
+
+
+
+def lexical_domain(
+
+    tokens: list[str],
+
+    text: str,
+
+    content: list[str],
+
+    language_profile: dict[str, Any],
+
+) -> tuple[DomainScore, dict[str, float]]:
+
+    total = max(len(tokens), 1)
+
+    unique = len(set(tokens))
+
+    filler_hits = estimate_filler_hits(tokens, text)
+
+
+
+    ttr = unique / total
+
+    density = len(content) / total
+
+    filler_rate = (filler_hits / total) * 100.0
+
+
+
+    ttr_target = pick_language_target(language_profile, english=0.52, hinglish=0.57, hindi=0.56, multilingual=0.55)
+
+    density_target = pick_language_target(language_profile, english=0.58, hinglish=0.63, hindi=0.61, multilingual=0.60)
+
+    filler_low = pick_language_target(language_profile, english=2.0, hinglish=3.5, hindi=3.5, multilingual=3.0)
+
+    filler_high = pick_language_target(language_profile, english=12.0, hinglish=20.0, hindi=17.0, multilingual=17.0)
+
+
+
+    s_ttr = clamp01(abs(ttr - ttr_target) / 0.30)
+
+    s_density = clamp01(abs(density - density_target) / 0.25)
+
+    s_filler = scale_linear(filler_rate, filler_low, filler_high)
+
+
+
+    overall = clamp01((0.4 * s_ttr) + (0.35 * s_density) + (0.25 * s_filler))
+
+
+
+    details = {
+
+        "ttr": round(s_ttr, 4),
+
+        "density": round(s_density, 4),
+
+        "filler_rate": round(s_filler, 4),
+
+    }
+
+    raw = {
+
+        "ttr": round(ttr, 4),
+
+        "lexical_density": round(density, 4),
+
+        "filler_rate_per_100w": round(filler_rate, 2),
+
+    }
+
+    return DomainScore(round(overall, 4), details), raw
+
+
+
+
+
+def semantic_domain(sentences: list[str]) -> tuple[DomainScore, dict[str, float]]:
+
+    if len(sentences) < 2:
+
+        coherence = 0.16
+
+        idea_density = 0.45
+
+        tangentiality = 0.55
+
+    else:
+
+        sentence_content = [set(content_words(tokenize_words(s))) for s in sentences]
+
+        pairwise = [jaccard(sentence_content[i], sentence_content[i + 1]) for i in range(len(sentence_content) - 1)]
+
+        coherence = mean(pairwise, default=0.12)
+
+        avg_content_len = mean([len(x) for x in sentence_content], default=0.0)
+
+        idea_density = clamp01(avg_content_len / 14.0)
+
+        tangentiality = clamp01(1.0 - coherence)
+
+    s_coherence = scale_inverse(coherence, good=0.22, poor=0.05)
+
+    s_idea_density = scale_inverse(idea_density, good=0.65, poor=0.25)
+
+    s_tangentiality = scale_linear(tangentiality, low=0.35, high=0.85)
+
+
+
+    overall = clamp01((0.45 * s_coherence) + (0.30 * s_idea_density) + (0.25 * s_tangentiality))
+
+
+
+    details = {
+
+        "coherence": round(s_coherence, 4),
+
+        "idea_density": round(s_idea_density, 4),
+
+        "tangentiality": round(s_tangentiality, 4),
+
+    }
+
+    raw = {
+
+        "coherence_index": round(coherence, 4),
+
+        "idea_density_index": round(idea_density, 4),
+
+        "tangentiality_index": round(tangentiality, 4),
+
+    }
+
+    return DomainScore(round(overall, 4), details), raw
+
+
+
+
+
+def prosody_domain(
+
+    tokens: list[str],
+
+    text: str,
+
+    pause_map: Optional[list[float]],
+
+    audio_duration: Optional[float],
+
+    language_profile: dict[str, Any],
+
+) -> tuple[DomainScore, dict[str, float], bool]:
+
+    word_count = max(len(tokens), 1)
+
+    pauses = [float(p) for p in (pause_map or []) if p >= 0]
+
+    has_audio_prosody = bool(pauses)
+
+
+
+    if audio_duration and audio_duration > 5.0:
+
+        duration_seconds = audio_duration
+
+    else:
+
+        estimated_speech_seconds = word_count / 2.5
+
+        duration_seconds = estimated_speech_seconds + sum(pauses)
+
+
+
+    duration_minutes = max(duration_seconds / 60.0, 0.1)
+
+    speech_rate = word_count / duration_minutes
+
+
+
+    if pauses:
+
+        pause_freq = len(pauses) / duration_minutes
+
+        pause_hesitation = sum(1 for p in pauses if p >= 0.8) / len(pauses)
+
+        lexical_hesitation = clamp01(estimate_filler_hits(tokens, text) / max(word_count, 1))
+
+        hesitation_ratio = clamp01((0.7 * pause_hesitation) + (0.3 * lexical_hesitation))
+
+    else:
+
+        punctuation_pauses = len(re.findall(r"[,;:\-]", text))
+
+        pause_freq = (punctuation_pauses / max(word_count, 1)) * 100
+
+        hesitation_ratio = clamp01(estimate_filler_hits(tokens, text) / max(word_count, 1))
+
+
+
+    speech_rate_target = pick_language_target(language_profile, english=140.0, hinglish=132.0, hindi=126.0, multilingual=133.0)
+
+    s_rate = clamp01(abs(speech_rate - speech_rate_target) / 95.0)
+
+    s_pause = scale_linear(pause_freq, low=8.0, high=30.0)
+
+    s_hes = scale_linear(hesitation_ratio, low=0.08, high=0.35)
+
+
+
+    overall = clamp01((0.4 * s_rate) + (0.35 * s_pause) + (0.25 * s_hes))
+
+
+
+    details = {
+
+        "speech_rate": round(s_rate, 4),
+
+        "pause_freq": round(s_pause, 4),
+
+        "hesitation": round(s_hes, 4),
+
+    }
+
+    raw = {
+
+        "speech_rate_wpm": round(speech_rate, 1),
+
+        "pause_frequency_per_min": round(pause_freq, 2),
+
+        "hesitation_ratio": round(hesitation_ratio, 4),
+
+        "duration_seconds": round(duration_seconds, 2),
+
+    }
+
+    return DomainScore(round(overall, 4), details), raw, has_audio_prosody
+
+
+
+def syntax_domain(
+
+    tokens: list[str],
+
+    sentences: list[str],
+
+    text: str,
+
+    language_profile: dict[str, Any],
+
+) -> tuple[DomainScore, dict[str, float]]:
+
+    sentence_count = max(len(sentences), 1)
+
+    mlu = len(tokens) / sentence_count
+
+
+
+    per_sentence_depth = []
+
+    for s in sentences:
+
+        stoks = tokenize_words(s)
+
+        sub_count = sum(1 for t in stoks if t in SUBORDINATORS)
+
+        comma_count = s.count(",")
+
+        per_sentence_depth.append(sub_count + (comma_count * 0.5))
+
+    clause_depth = mean(per_sentence_depth, default=0.0)
+
+
+
+    passive_matches = re.findall(r"\b(?:is|are|was|were|be|been|being)\s+\w+(?:ed|en)\b", text.lower())
+
+    passive_ratio = len(passive_matches) / max(sentence_count, 1)
+
+
+
+    mlu_target = pick_language_target(language_profile, english=17.0, hinglish=15.0, hindi=14.5, multilingual=15.5)
+
+    depth_low = pick_language_target(language_profile, english=2.0, hinglish=1.5, hindi=1.4, multilingual=1.6)
+
+    depth_high = pick_language_target(language_profile, english=6.5, hinglish=5.7, hindi=5.3, multilingual=5.8)
+
+
+
+    s_mlu = clamp01(abs(mlu - mlu_target) / 12.0)
+
+    s_depth = scale_linear(clause_depth, low=depth_low, high=depth_high)
+
+    s_passive = scale_linear(passive_ratio, low=0.15, high=1.2)
+
+
+
+    passive_weight = pick_language_target(language_profile, english=0.20, hinglish=0.12, hindi=0.05, multilingual=0.10)
+
+    mlu_weight = 0.45 + ((0.20 - passive_weight) * 0.55)
+
+    depth_weight = 1.0 - mlu_weight - passive_weight
+
+
+
+    overall = clamp01((mlu_weight * s_mlu) + (depth_weight * s_depth) + (passive_weight * s_passive))
+
+
+
+    details = {
+
+        "mlu": round(s_mlu, 4),
+
+        "clause_depth": round(s_depth, 4),
+
+        "passive_ratio": round(s_passive, 4),
+
+    }
+
+    raw = {
+
+        "mean_length_utterance": round(mlu, 2),
+
+        "clause_depth_index": round(clause_depth, 2),
+
+        "passive_ratio": round(passive_ratio, 3),
+
+    }
+
+    return DomainScore(round(overall, 4), details), raw
+
+
+
+
+
+def affective_domain(tokens: list[str], text: str) -> tuple[DomainScore, dict[str, float]]:
+
+    total = max(len(tokens), 1)
+
+    pos = sum(1 for t in tokens if t in POSITIVE_WORDS)
+
+    neg = sum(1 for t in tokens if t in NEGATIVE_WORDS)
+
+    arousal = sum(1 for t in tokens if t in AROUSAL_WORDS)
+
+    hedge = estimate_hedge_hits(tokens, text)
+
+
+
+    valence = (pos - neg) / (pos + neg + 1)
+
+    valence_01 = (valence + 1.0) / 2.0
+
+    arousal_rate = (arousal / total) * 100.0
+
+    certainty = 1.0 - clamp01(hedge / max(total * 0.15, 1.0))
+
+
+
+    s_valence = scale_inverse(valence_01, good=0.62, poor=0.20)
+
+    s_arousal = scale_linear(arousal_rate, low=3.0, high=14.0)
+
+    s_certainty = scale_inverse(certainty, good=0.72, poor=0.32)
+
+    overall = clamp01((0.4 * s_valence) + (0.35 * s_arousal) + (0.25 * s_certainty))
+
+
+
+    details = {
+
+        "valence": round(s_valence, 4),
+
+        "arousal": round(s_arousal, 4),
+
+        "certainty": round(s_certainty, 4),
+
+    }
+
+    raw = {
+
+        "valence_score": round(valence_01, 4),
+
+        "arousal_rate_per_100w": round(arousal_rate, 2),
+
+        "certainty_index": round(certainty, 4),
+
+    }
+
+    return DomainScore(round(overall, 4), details), raw
+
+
+
+
+
+def compute_confidence(
+
+    word_count: int, sentence_count: int, has_audio_prosody: bool, repeat_ratio: float
+
+) -> tuple[float, list[str]]:
+
+    notes: list[str] = []
+
+    c_words = clamp01(word_count / 180.0)
+
+    c_sents = clamp01(sentence_count / 8.0)
+
+    c_repeat = clamp01(1.0 - (repeat_ratio * 1.4))
+
+    c_audio = 1.0 if has_audio_prosody else 0.55
+
+
+
+    confidence = clamp01((0.45 * c_words) + (0.2 * c_sents) + (0.2 * c_repeat) + (0.15 * c_audio))
+
+
+
+    if word_count < 60:
+
+        notes.append("Low sample length. Interpret results cautiously.")
+
+    if not has_audio_prosody:
+
+        notes.append("Prosody is inferred from text patterns because pause-map audio features were not provided.")
+
+    if repeat_ratio > 0.45:
+
+        notes.append("High repetition detected, which can reduce semantic reliability.")
+
+
+
+    return round(confidence, 4), notes
+
+
+
+
+
+def compute_analysis_state(
+
+    text: str,
+
+    pause_map: Optional[list[float]],
+
+    audio_duration: Optional[float],
+
+    detected_language: Optional[str] = None,
+
+    hinted_profile: Optional[dict[str, Any]] = None,
+
+) -> AnalysisState:
+
+    tokens = tokenize_words(text)
+
+    sentences = split_sentences(text)
+
+    cwords = content_words(tokens)
+
+    language_profile = detect_language_profile(
+
+        text,
+
+        hinted_language=detected_language,
+
+        hinted_profile=hinted_profile,
+
+    )
+
+
+
+    repeat_ratio = 1.0 - (len(set(tokens)) / max(len(tokens), 1))
+
+
+
+    lexical, lexical_raw = lexical_domain(tokens, text, cwords, language_profile)
+
+    semantic, semantic_raw = semantic_domain(sentences)
+
+    prosody, prosody_raw, has_audio = prosody_domain(tokens, text, pause_map, audio_duration, language_profile)
+
+    syntax, syntax_raw = syntax_domain(tokens, sentences, text, language_profile)
+
+    affective, affective_raw = affective_domain(tokens, text)
+
+    confidence, quality_notes = compute_confidence(
+
+        word_count=len(tokens),
+
+        sentence_count=len(sentences),
+
+        has_audio_prosody=has_audio,
+
+        repeat_ratio=repeat_ratio,
+
+    )
+
+    quality_notes.append(
+
+        "Detected language mode: "
+
+        + str(language_profile.get("label", "multilingual")).title()
+
+        + f" (Hindi {round(float(language_profile.get('hindi_ratio', 0.0)) * 100)}%, "
+
+        + f"English {round(float(language_profile.get('english_ratio', 0.0)) * 100)}%)."
+
+    )
+
+
+
+    scores = {
+
+        "lexical": lexical,
+
+        "semantic": semantic,
+
+        "prosody": prosody,
+
+        "syntax": syntax,
+
+        "affective": affective,
+
+    }
+
+
+
+    weighted = (
+
+        (0.22 * lexical.overall)
+
+        + (0.23 * semantic.overall)
+
+        + (0.18 * prosody.overall)
+
+        + (0.22 * syntax.overall)
+
+        + (0.15 * affective.overall)
+
+    )
+
+
+
+    confidence_factor = 0.75 + (0.25 * confidence)
+
+    overall_load = clamp01(weighted * confidence_factor)
+
+
+
+    metrics = {
+
+        "word_count": len(tokens),
+
+        "sentence_count": len(sentences),
+
+        "repeat_ratio": round(repeat_ratio, 4),
+
+        "language_profile": language_profile,
+
+        "lexical": lexical_raw,
+
+        "semantic": semantic_raw,
+
+        "prosody": prosody_raw,
+
+        "syntax": syntax_raw,
+
+        "affective": affective_raw,
+
+    }
+
+
+
+    return AnalysisState(
+
+        scores=scores,
+
+        overall_load=round(overall_load, 4),
+
+        confidence=confidence,
+
+        quality_notes=quality_notes,
+
+        language_profile=language_profile,
+
+        metrics=metrics,
+
+    )
+
+
+
+
+
+def severity_from_score(value: float) -> str:
+
+    if value >= 0.72:
+
+        return "high"
+
+    if value >= 0.42:
+
+        return "moderate"
+
+    return "low"
+
+
+
+def level_from_overall(overall_load: float, confidence: float) -> str:
+
+    if overall_load >= 0.68:
+
+        base = "high"
+
+    elif overall_load >= 0.44:
+
+        base = "moderate"
+
+    else:
+
+        base = "low"
+
+
+
+    if confidence < 0.45 and base == "high":
+
+        return "moderate"
+
+    return base
+
+
+
+
+
+def summary_fallback(state: AnalysisState, risk_level: str) -> str:
+
+    top_domain = max(state.scores.items(), key=lambda kv: kv[1].overall)[0]
+
+    top_value = state.scores[top_domain].overall
+
+    confidence_pct = round(state.confidence * 100)
+
+    language_mode = str(state.language_profile.get("label", "multilingual"))
+
+    return (
+
+        f"This {language_mode} speech analysis found a {risk_level} overall cognitive load signal based on linguistic and timing features. "
+
+        f"The strongest deviation appeared in {top_domain} markers (score {top_value:.2f}). "
+
+        f"Confidence is {confidence_pct}% and this output is screening support only, not a diagnosis."
+
+    )
+
+
+
+
+
+def make_highlights(state: AnalysisState) -> list[dict[str, Any]]:
+
+    sorted_domains = sorted(state.scores.items(), key=lambda kv: kv[1].overall, reverse=True)
+
+    highlights: list[dict[str, Any]] = []
+
+    for domain, score in sorted_domains[:3]:
+
+        if score.overall >= 0.66:
+
+            finding = "Elevated deviation from expected baseline in this domain."
+
+        elif score.overall >= 0.42:
+
+            finding = "Mild-to-moderate deviation with mixed stability."
+
+        else:
+
+            finding = "Signals remain within expected variation for this domain."
+
+
+
+        highlights.append(
+
+            {
+
+                "region": DOMAIN_REGION[domain],
+
+                "activation": round(score.overall, 4),
+
+                "finding": finding,
+
+                "clinical_context": "Screening signal only. Interpret alongside clinical judgement and repeated assessments.",
+
+            }
+
+        )
+
+    return highlights
+
+
+
+
+
+def make_indicators(state: AnalysisState) -> list[dict[str, Any]]:
+
+    indicators: list[dict[str, Any]] = []
+
+    for domain, dscore in state.scores.items():
+
+        for k, v in dscore.details.items():
+
+            if v < 0.42:
+
+                continue
+
+            indicators.append(
+
+                {
+
+                    "indicator": f"{domain.title()} · {k.replace('_', ' ').title()}",
+
+                    "severity": severity_from_score(v),
+
+                    "explanation": f"Computed score {v:.2f} from measured input features; higher means greater deviation from baseline patterns.",
+
+                }
+
+            )
+
+    indicators.sort(key=lambda x: {"high": 2, "moderate": 1, "low": 0}[x["severity"]], reverse=True)
+
+    return indicators[:6]
+
+
+
+
+
+def recommendation_for_level(level: str, confidence: float) -> str:
+
+    if level == "high":
+
+        return (
+
+            "Repeat this assessment with a longer sample, then discuss the combined results with a qualified clinician. "
+
+            "Do not treat this result as a diagnosis."
+
+        )
+
+    if level == "moderate":
+
+        return (
+
+            "Collect 1-2 additional samples across different times of day to confirm trend stability before drawing conclusions."
+
+        )
+
+    if confidence < 0.5:
+
+        return "Provide a longer speech sample for stronger reliability before interpreting the result."
+
+    return "Current signals are relatively stable. Continue periodic monitoring rather than one-off interpretation."
+
+
+
+
+
+async def fetch_available_models() -> list[str]:
+
+    if not GROQ_API_KEY:
+
+        return []
+
+
+
+    async with _MODEL_CACHE_LOCK:
+
+        now = time.time()
+
+        if now - float(_MODEL_CACHE["updated"]) < MODEL_DISCOVERY_TTL_SECONDS:
+
+            return list(_MODEL_CACHE["models"])
+
+
+
+        headers = {"Authorization": f"Bearer {GROQ_API_KEY}"}
+
+        try:
+
+            async with httpx.AsyncClient(timeout=GROQ_TIMEOUT_SECONDS) as client:
+
+                res = await client.get(f"{GROQ_API_BASE}/models", headers=headers)
+
+                res.raise_for_status()
+
+                data = res.json().get("data", [])
+
+                models = sorted({item.get("id", "") for item in data if item.get("id")})
+
+                _MODEL_CACHE["updated"] = now
+
+                _MODEL_CACHE["models"] = models
+
+                return models
+
+        except Exception:
+
+            return list(_MODEL_CACHE["models"])
+
+
+
+
+
+def pick_model(available: list[str], override: str, candidates: list[str]) -> Optional[str]:
+
+    if override and override in available:
+
+        return override
+
+
+
+    for m in candidates:
+
+        if m in available:
+
+            return m
+
+    for m in available:
+
+        lowered = m.lower()
+
+        if "instruct" in lowered or "versatile" in lowered or "gpt-oss" in lowered:
+
+            return m
+
+
+
+    return available[0] if available else None
+
+
+
+
+
+async def groq_chat(model: str, system: str, user: str, temperature: float = 0.2) -> Optional[str]:
+
+    if not GROQ_API_KEY or not model:
+
+        return None
+
+
+
+    headers = {
+
+        "Authorization": f"Bearer {GROQ_API_KEY}",
+
+        "Content-Type": "application/json",
+
+    }
+
+    payload = {
+
+        "model": model,
+
+        "temperature": temperature,
+
+        "messages": [
+
+            {"role": "system", "content": system},
+
+            {"role": "user", "content": user},
+
+        ],
+
+    }
+
+
+
+    try:
+
+        async with httpx.AsyncClient(timeout=GROQ_TIMEOUT_SECONDS) as client:
+
+            res = await client.post(f"{GROQ_API_BASE}/chat/completions", headers=headers, json=payload)
+
+            res.raise_for_status()
+
+            data = res.json()
+
+            return data["choices"][0]["message"]["content"].strip()
+
+    except Exception:
+
+        return None
+
+
+
+
+
+async def compose_safe_summary(state: AnalysisState, risk_level: str) -> tuple[str, dict[str, Optional[str]]]:
+
+    available = await fetch_available_models()
+
+    reasoning_model = pick_model(available, OVERRIDE_REASONING_MODEL, PREFERRED_REASONING_MODELS)
+
+    safety_model = pick_model(available, OVERRIDE_SAFETY_MODEL, PREFERRED_SAFETY_MODELS)
+
+
+
+    model_meta = {
+
+        "reasoning_model": reasoning_model,
+
+        "safety_model": safety_model,
+
+    }
+
+
+
+    baseline_summary = summary_fallback(state, risk_level)
+
+    if not reasoning_model:
+
+        return baseline_summary, model_meta
+
+
+
+    features_for_prompt = {
+
+        "risk_level": risk_level,
+
+        "overall_cognitive_load": state.overall_load,
+
+        "confidence": state.confidence,
+
+        "language_profile": state.language_profile,
+
+        "scores": {k: v.overall for k, v in state.scores.items()},
+
+        "quality_notes": state.quality_notes,
+
+        "metrics": state.metrics,
+
+    }
+
+    system = (
+
+        "You summarize computational language-screening outputs. "
+
+        "English, Hindi, and code-mixed Hinglish samples are all valid and should be interpreted fairly. "
+
+        "Never diagnose disease, never use alarming wording, and always state uncertainty when confidence is limited. "
+
+        "Output exactly 2-3 sentences in plain text."
+
+    )
+
+    user = "Write a careful summary for this analysis:\n" + json.dumps(features_for_prompt)
+
+
+
+    summary = await groq_chat(reasoning_model, system, user, temperature=0.15)
+
+    if not summary:
+
+        return baseline_summary, model_meta
+
+
+
+    if safety_model:
+
+        safety_system = (
+
+            "You are a safety editor for health-adjacent UX. "
+
+            "Rewrite text to avoid panic, avoid diagnosis claims, and keep uncertainty explicit. "
+
+            "Keep 2-3 sentences."
+
+        )
+
+        safety_user = (
+
+            "Rewrite this summary to be non-alarmist and clinically careful while keeping factual content:\n"
+
+            + summary
+
+            + "\n\nConfidence: "
+
+            + str(state.confidence)
+
+        )
+
+        safe = await groq_chat(safety_model, safety_system, safety_user, temperature=0.1)
+
+        if safe:
+
+            summary = safe
+
+
+
+    return summary, model_meta
+
+
+
+
+
+@app.get("/health")
+
+async def health() -> dict[str, Any]:
+
+    available = await fetch_available_models()
+
+    transcribe_caps = transcription_model_capabilities(GROQ_TRANSCRIBE_MODEL)
+
+    return {
+
+        "ok": True,
+
+        "service": "cortexflow-backend",
+
+        "groq_configured": bool(GROQ_API_KEY),
+
+        "model_count": len(available),
+
+        "transcription_model": GROQ_TRANSCRIBE_MODEL,
+
+        "transcription_capabilities": transcribe_caps,
+
+    }
+
+
+
+
+
+@app.get("/models/recommended")
+
+async def models_recommended() -> dict[str, Any]:
+
+    available = await fetch_available_models()
+
+    transcribe_caps = transcription_model_capabilities(GROQ_TRANSCRIBE_MODEL)
+
+    return {
+
+        "available_models": available,
+
+        "recommended": {
+
+            "reasoning": pick_model(available, OVERRIDE_REASONING_MODEL, PREFERRED_REASONING_MODELS),
+
+            "safety": pick_model(available, OVERRIDE_SAFETY_MODEL, PREFERRED_SAFETY_MODELS),
+
+            "transcription": GROQ_TRANSCRIBE_MODEL,
+
+        },
+
+        "transcription_capabilities": transcribe_caps,
+
+        "notes": {
+
+            "production_primary": "openai/gpt-oss-120b",
+
+            "production_fallback": "llama-3.3-70b-versatile",
+
+            "fast_fallback": "openai/gpt-oss-20b",
+
+            "transcription_accuracy_primary": "whisper-large-v3",
+
+            "transcription_speed_price_primary": "whisper-large-v3-turbo",
+
+            "transcription_language_note": "Both Whisper models are multilingual and suitable for Hindi/Hinglish speech.",
+
+        },
+
+    }
+
+
+
+@app.post("/analyze")
+
+async def analyze(req: AnalyzeRequest):
+
+    text = ensure_nonempty_text(req)
+
+    session_id = req.session_id or str(uuid.uuid4())
+
+
+
+    async def generate():
+
+        for idx, step_name in enumerate(STEP_NAMES):
+
+            yield safe_step_event(step_name, "running" if idx == 0 else "pending")
+
+
+
+        try:
+
+            state = compute_analysis_state(
+
+                text,
+
+                req.pause_map,
+
+                req.audio_duration,
+
+                detected_language=req.detected_language,
+
+                hinted_profile=req.language_profile,
+
+            )
+
+            yield safe_step_event("STT preprocessor", "done", "Input normalized and validated")
+
+            yield safe_step_event("Lexical agent", "running")
+
+
+
+            await asyncio.sleep(0)
+
+            yield safe_step_event("Lexical agent", "done")
+
+            yield safe_step_event("Semantic agent", "running")
+
+
+
+            await asyncio.sleep(0)
+
+            yield safe_step_event("Semantic agent", "done")
+
+            yield safe_step_event("Prosody agent", "running")
+
+
+
+            await asyncio.sleep(0)
+
+            yield safe_step_event("Prosody agent", "done")
+
+            yield safe_step_event("Syntax agent", "running")
+
+
+
+            await asyncio.sleep(0)
+
+            yield safe_step_event("Syntax agent", "done")
+
+            yield safe_step_event("Biomarker mapper", "running")
+
+
+
+            scores_payload = {
+
+                domain: {**score.details, "overall": score.overall}
+
+                for domain, score in state.scores.items()
+
+            }
+
+
+
+            yield safe_step_event("Biomarker mapper", "done")
+
+            yield safe_step_event("Report composer", "running")
+
+
+
+            risk_level = level_from_overall(state.overall_load, state.confidence)
+
+            summary, model_meta = await compose_safe_summary(state, risk_level)
+
+
+
+            report = {
+
+                "summary": summary,
+
+                "risk_level": risk_level,
+
+                "overall_cognitive_load": state.overall_load,
+
+                "highlights": make_highlights(state),
+
+                "risk_indicators": make_indicators(state),
+
+                "recommendation": recommendation_for_level(risk_level, state.confidence),
+
+                "disclaimer": (
+
+                    "This tool is a non-diagnostic screening aid. It can be wrong and must not be used as a standalone "
+
+                    "medical decision system. If you are concerned, consult a qualified clinician."
+
+                ),
+
+                "quality": {
+
+                    "confidence": state.confidence,
+
+                    "notes": state.quality_notes,
+
+                },
+
+                "language_profile": state.language_profile,
+
+                "model_info": model_meta,
+
+            }
+
+            yield safe_step_event("Report composer", "done")
+
+
+
+            payload = {
+
+                "type": "end",
+
+                "message": summary,
+
+                "scores": scores_payload,
+
+                "report": report,
+
+                "session_id": session_id,
+
+            }
+
+            yield (json.dumps(payload) + "\n").encode()
+
+
+
+        except HTTPException as exc:
+
+            yield (json.dumps({"type": "error", "message": exc.detail}) + "\n").encode()
+
+        except Exception as exc:
+
+            yield (json.dumps({"type": "error", "message": f"Analysis failed: {str(exc)}"}) + "\n").encode()
+
+
+
+    return StreamingResponse(
+
+        generate(),
+
+        media_type="text/plain",
+
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+
+    )
+