first commit

.env.example

@@ -0,0 +1,31 @@
+# Copy to .env locally; use HF Space Secrets in deployment.
+# Frontend never reads these — backend model_router only.
+APP_ENV=development
+MAX_ROUNDS=6
+
+DEFAULT_MODEL_MODE=premium_nvidia
+
+# NVIDIA Nemotron 3 Nano Omni 30B-A3B (primary premium model — backend-only API)
+NVIDIA_API_KEY=
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
+
+# OpenBMB MiniCPM models
+OPENBMB_API_KEY=
+OPENBMB_BASE_URL=
+MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
+MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
+MINICPM_TEXT_BACKEND=api_or_local
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+
+# Hugging Face (model download / Space)
+HF_TOKEN=
+
+# Audio transcription fallback only (not the primary judge)
+WHISPER_FALLBACK_ENABLED=true
+WHISPER_MODEL_SIZE=tiny
+
+# Feature flags
+ENABLE_DECK_CRITIQUE=true
+ENABLE_DEAL_BATTLE=true
+ENABLE_VOICE_MODE=true

.gitignore

@@ -0,0 +1,43 @@
+# Secrets — never commit real keys
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Node (if added later)
+node_modules/
+
+# Gradio runtime / uploads
+.gradio/
+
+# Local model weights & generated media (large / machine-specific)
+models/
+*.gguf
+*.wav
+*.mp3

README.md

@@ -0,0 +1,82 @@
+---
+title: PitchFight AI
+emoji: ⚔️
+colorFrom: red
+colorTo: yellow
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+
+# PitchFight AI
+
+**Your first tough pitch should not be in front of a real judge.**
+
+A voice-and-text AI sparring arena for student founders — built for the Hugging Face **Build Small Hackathon** (Backyard AI track).
+
+## One-Line Pitch
+
+PitchFight AI is a voice-and-text AI sparring arena where student founders practice tough startup pitches, get grilled by realistic AI judges under 32B parameters, and receive a scorecard that shows exactly how to answer better.
+
+## Strategic Direction
+
+This build prioritizes **demo strength**, **model quality**, and **sponsor-model alignment** — not the Off-the-Grid badge.
+
+| Priority | Detail |
+|---|---|
+| **Hackathon rules** | ≤32B models, Gradio, HF Spaces, demo-first |
+| **Primary premium model** | NVIDIA Nemotron 3 Nano Omni 30B-A3B (backend-only API) |
+| **Frontend API** | `fetch()` → `/api/...` only — never model provider APIs |
+| **OpenBMB modes** | MiniCPM-o, MiniCPM5-1B, MiniCPM-V 4.6 |
+| **Voice fallback** | faster-whisper local transcription |
+| **UI** | Custom HTML/CSS/JS via Gradio Server (not default Gradio) |
+| **Secrets** | API keys in HF Space Secrets / backend `.env` only |
+
+> **Off-the-Grid is not targeted** in this build. Sponsor APIs are used intentionally for the highest-quality demo.
+
+## Target Badges / Prizes
+
+Backyard AI · Best Demo · Best Agent · Off-Brand · NVIDIA Nemotron Quest · OpenBMB Awards · Sharing is Caring · Field Notes · Tiny Titan (Tiny Mode)
+
+## Current Status
+
+**Phase 1 complete** — Gradio Server skeleton + custom frontend + mock battle/scorecard APIs.
+
+See [`docs/PHASE_WISE_PLAN.md`](docs/PHASE_WISE_PLAN.md) for the full 14-phase roadmap.
+
+## Run Locally
+
+```bash
+python -m venv venv
+# Windows: .\venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+cp .env.example .env   # add API keys for Phase 2+
+python app.py
+```
+
+Open the URL printed in your terminal (typically `http://127.0.0.1:7860`).
+
+Phase 1 runs with **mock responses** — no API keys required. Real model routing begins in **Phase 2**.
+
+## Backend API
+
+PitchFight AI exposes **clean custom project APIs under `/api/...`**. Gradio internal routes (`/gradio_api/*`, `/queue`, `/upload`, etc.) may appear in OpenAPI/Swagger — those are **framework runtime routes**, not product endpoints.
+
+See **[`docs/BACKEND_API.md`](docs/BACKEND_API.md)** for the full API reference.
+
+## Project Structure
+
+- `app.py` — Gradio Server entrypoint + `/api/*` REST routes
+- `core/api_handlers.py` — shared handler logic (REST + Gradio)
+- `core/` — session, persona, scoring, model clients (Phases 2+)
+- `config/` — personas, attack tags, rubric, samples
+- `frontend/` — custom battle arena UI (`fetch` → `/api/*`)
+- `docs/` — phase plan, models, prompts, demo notes, backend API
+
+## Documentation
+
+- [Phase-Wise Plan](docs/PHASE_WISE_PLAN.md)
+- [Model Strategy](docs/MODELS_FINAL.md)
+- [Nemotron Omni Audio Architecture](docs/NEMOTRON_OMNI_AUDIO.md)
+- [Full Documentation](docs/DOCUMENTATION.md)
+- [Demo Notes](docs/DEMO_NOTES.md)

app.py

@@ -0,0 +1,134 @@
+"""PitchFight AI — Gradio Server app with custom frontend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from fastapi import Body
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from gradio import Server
+
+from core.api_handlers import (
+    handle_chat_round,
+    handle_deck_critique_placeholder,
+    handle_deal_session_placeholder,
+    handle_end_battle,
+    handle_load_sample,
+    handle_reset_session,
+    handle_start_session,
+    handle_voice_pitch_placeholder,
+)
+from core import model_router
+
+APP_VERSION = "0.1.0"
+FRONTEND_DIR = Path(__file__).parent / "frontend"
+
+app = Server()
+
+
+# ---------------------------------------------------------------------------
+# PitchFight REST API (product endpoints — use these from the custom frontend)
+# ---------------------------------------------------------------------------
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    """Health check for app status."""
+    return {"status": "ok", "app": "PitchFight AI", "version": APP_VERSION}
+
+
+@app.get("/api/model-health")
+async def api_model_health() -> dict[str, Any]:
+    """Model provider configuration status. Keys are never exposed."""
+    return model_router.get_model_health()
+
+
+@app.post("/api/load-sample")
+def api_load_sample() -> dict[str, Any]:
+    return handle_load_sample()
+
+
+@app.post("/api/start-session")
+def api_start_session(payload: dict[str, Any] = Body(...)) -> dict[str, Any]:
+    return handle_start_session(payload)
+
+
+@app.post("/api/chat-round")
+def api_chat_round(payload: dict[str, Any] = Body(...)) -> dict[str, Any]:
+    return handle_chat_round(payload)
+
+
+@app.post("/api/end-battle")
+def api_end_battle(payload: dict[str, Any] = Body(...)) -> dict[str, Any]:
+    return handle_end_battle(payload)
+
+
+@app.post("/api/reset-session")
+def api_reset_session(payload: dict[str, Any] = Body(...)) -> dict[str, Any]:
+    return handle_reset_session(payload)
+
+
+@app.post("/api/voice-pitch")
+def api_voice_pitch(payload: dict[str, Any] = Body(default_factory=dict)) -> dict[str, str]:
+    return handle_voice_pitch_placeholder(payload)
+
+
+@app.post("/api/start-deal-session")
+def api_start_deal_session(payload: dict[str, Any] = Body(default_factory=dict)) -> dict[str, str]:
+    return handle_deal_session_placeholder(payload)
+
+
+@app.post("/api/deck-critique")
+def api_deck_critique(payload: dict[str, Any] = Body(default_factory=dict)) -> dict[str, str]:
+    return handle_deck_critique_placeholder(payload)
+
+
+# ---------------------------------------------------------------------------
+# Gradio @app.api compatibility (same handlers — for gradio_client / queue)
+# ---------------------------------------------------------------------------
+
+
+@app.api(name="load_sample")
+def gradio_load_sample() -> dict[str, Any]:
+    return handle_load_sample()
+
+
+@app.api(name="start_session")
+def gradio_start_session(payload: dict[str, Any]) -> dict[str, Any]:
+    return handle_start_session(payload)
+
+
+@app.api(name="chat_round")
+def gradio_chat_round(payload: dict[str, Any]) -> dict[str, Any]:
+    return handle_chat_round(payload)
+
+
+@app.api(name="end_battle")
+def gradio_end_battle(payload: dict[str, Any]) -> dict[str, Any]:
+    return handle_end_battle(payload)
+
+
+@app.api(name="reset_session")
+def gradio_reset_session(payload: dict[str, Any]) -> dict[str, Any]:
+    return handle_reset_session(payload)
+
+
+# ---------------------------------------------------------------------------
+# Frontend
+# ---------------------------------------------------------------------------
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage() -> HTMLResponse:
+    """Serve the custom PitchFight frontend."""
+    index_path = FRONTEND_DIR / "index.html"
+    return HTMLResponse(index_path.read_text(encoding="utf-8"))
+
+
+app.mount("/frontend", StaticFiles(directory=str(FRONTEND_DIR)), name="frontend")
+
+
+if __name__ == "__main__":
+    app.launch(show_error=True)

config/attack_tags.json

@@ -0,0 +1,32 @@
+{
+  "skeptical_vc": [
+    "Market Size",
+    "Moat",
+    "Retention",
+    "Revenue Logic",
+    "First 100 Users",
+    "Why Now",
+    "Competition",
+    "Defensibility"
+  ],
+  "technical_judge": [
+    "AI Justification",
+    "Architecture",
+    "Scalability",
+    "Latency",
+    "Data Quality",
+    "Failure Mode",
+    "Simpler Alternative",
+    "Technical Feasibility"
+  ],
+  "hackathon_judge": [
+    "Novelty",
+    "Demo Clarity",
+    "MVP Strength",
+    "User Pain",
+    "AI Load-Bearing",
+    "Backyard Fit",
+    "Practical Impact",
+    "Judging Memorability"
+  ]
+}

config/personas.json

@@ -0,0 +1,46 @@
+{
+  "personas": [
+    {
+      "id": "skeptical_vc",
+      "name": "Morgan Vale",
+      "role": "Skeptical VC",
+      "tone": "Direct, ROI-focused, allergic to buzzwords",
+      "focus_areas": [
+        "Market Size",
+        "Moat",
+        "Retention",
+        "Revenue Logic",
+        "Defensibility"
+      ],
+      "opening_style": "Opens with a market or business-model challenge before asking for proof."
+    },
+    {
+      "id": "technical_judge",
+      "name": "Dr. Priya Nair",
+      "role": "Technical Judge",
+      "tone": "Precise, systems-minded, skeptical of AI theater",
+      "focus_areas": [
+        "AI Justification",
+        "Architecture",
+        "Scalability",
+        "Data Quality",
+        "Technical Feasibility"
+      ],
+      "opening_style": "Opens by questioning whether AI is necessary and how the system actually works."
+    },
+    {
+      "id": "hackathon_judge",
+      "name": "Jordan Keane",
+      "role": "Hackathon Judge",
+      "tone": "Fast-paced, demo-focused, prizes clarity over hype",
+      "focus_areas": [
+        "Novelty",
+        "Demo Clarity",
+        "MVP Strength",
+        "User Pain",
+        "Backyard Fit"
+      ],
+      "opening_style": "Opens with a sharp question about user pain, demo proof, or hackathon fit."
+    }
+  ]
+}

config/pitch_rubric.json

@@ -0,0 +1,11 @@
+{
+  "dimensions": {
+    "clarity": 15,
+    "problem_understanding": 20,
+    "market_awareness": 15,
+    "differentiation": 20,
+    "business_model": 15,
+    "objection_handling": 15
+  },
+  "total": 100
+}

config/sample_startups.json

@@ -0,0 +1,14 @@
+{
+  "startups": [
+    {
+      "name": "EventRadar AI",
+      "problem": "Students miss hackathons, tech events, and startup opportunities because discovery is scattered across WhatsApp groups, LinkedIn, Luma, college clubs, and random websites.",
+      "target_users": "College students, student founders, and early-stage builders.",
+      "solution": "AI-powered event discovery that ranks opportunities based on skills, goals, location, and deadline urgency.",
+      "why_ai": "The app does not just list events. It matches events to a student's profile and explains why each event is worth attending.",
+      "competitors": "Luma, LinkedIn Events, WhatsApp groups, college club pages.",
+      "traction": "Prototype built with scraped event data and ranking logic.",
+      "ask": "Hackathon prize and mentor feedback."
+    }
+  ]
+}

core/__init__.py

@@ -0,0 +1 @@
+"""PitchFight AI core modules."""

core/api_handlers.py

@@ -0,0 +1,512 @@
+"""PitchFight AI — shared API handler functions for REST and Gradio routes."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from dotenv import load_dotenv
+
+from core.attack_tags import get_attack_tags, get_next_attack_tag
+from core.persona_builder import build_persona_prompt
+from core.samples import get_sample_startup
+from core.scoring_engine import (
+    mock_scorecard,
+    generate_real_scorecard,
+    generate_claim_based_scorecard,
+    build_session_aware_fallback_scorecard,
+)
+from core.claim_extractor import extract_concrete_signals
+from core import battle_flow
+from core import model_router
+from core import session_manager
+from core.output_sanitizer import sanitize_model_output
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+MAX_ROUNDS = int(os.getenv("MAX_ROUNDS", "6"))
+
+OPENING_MESSAGES: dict[str, tuple[str, str]] = {
+    "skeptical_vc": (
+        "Market Size",
+        "How big is this really? Student event discovery sounds like a nice feature, not a venture-scale business.",
+    ),
+    "technical_judge": (
+        "AI Justification",
+        "Why does this need AI? A sorted event list with filters seems enough. What is the intelligence here?",
+    ),
+    "hackathon_judge": (
+        "User Pain",
+        "Students already lurk in WhatsApp groups. What pain are you solving that a shared Google Sheet cannot?",
+    ),
+}
+
+MOCK_FOLLOWUPS: dict[str, list[str]] = {
+    "skeptical_vc": [
+        "You named competitors but did not explain why students switch. What is your wedge for the first 100 users?",
+        "Where is the retention? Why would a student open this weekly instead of once before a hackathon?",
+        "Walk me through revenue. Who pays and why would they pay you instead of Luma or LinkedIn?",
+        "What stops a bigger platform from adding your ranking layer in a weekend?",
+        "Your traction sounds like a prototype. What metric proves demand, not just build activity?",
+        "If I gave you $50k today, what single milestone would prove this is investable?",
+    ],
+    "technical_judge": [
+        "What data do you rank on, and how do you keep event metadata fresh without manual cleanup?",
+        "If ranking is the core value, why is a small model better than deterministic scoring rules?",
+        "What happens when two students with different goals get the same top recommendation?",
+        "How does this scale beyond one campus without quality collapsing?",
+        "What is your failure mode when event sources break or duplicate listings?",
+        "Show me the simplest non-AI version. Why is that not good enough?",
+    ],
+    "hackathon_judge": [
+        "In one sentence: what is novel here versus another event aggregator?",
+        "If I only saw a 30-second demo, what would convince me the AI matching is real?",
+        "What did you ship this weekend that proves user pain, not just scraped listings?",
+        "Why is AI load-bearing in the MVP instead of optional polish?",
+        "How does this fit the Backyard AI theme beyond using a model as a label?",
+        "What will I remember about your project after judging 40 teams?",
+    ],
+}
+
+
+_HISTORY_WINDOW = 12  # max turns sent to Nemotron for live inference
+
+
+def pressure_level(round_number: int) -> str:
+    if round_number <= 2:
+        return "Medium"
+    if round_number <= 4:
+        return "High"
+    return "Extreme"
+
+
+def get_battle_phase(round_number: int) -> str:
+    """Return a battle phase label based on round count."""
+    if round_number <= 3:
+        return "explore"
+    if round_number <= 6:
+        return "pressure"
+    return "close"
+
+
+def _recent_history(session_id: str, max_turns: int = _HISTORY_WINDOW) -> list[dict]:
+    """Return at most max_turns recent history entries for live inference."""
+    full = session_manager.get_history(session_id)
+    return full[-max_turns:] if len(full) > max_turns else full
+
+
+def handle_load_sample() -> dict[str, Any]:
+    """Return the EventRadar AI demo startup."""
+    return {"startup": get_sample_startup()}
+
+
+# ---------------------------------------------------------------------------
+# Prompt builders
+# ---------------------------------------------------------------------------
+
+def _build_opening_messages(
+    startup: dict,
+    persona: str,
+    difficulty: str,
+    attack_tag: str,
+) -> list[dict[str, str]]:
+    """Build the OpenAI-format messages list for the opening judge question."""
+    system_prompt = build_persona_prompt(persona, startup, difficulty)
+    tags = get_attack_tags(persona)
+    tags_preview = ", ".join(tags[:4])
+
+    user_content = (
+        f"Current attack focus: {attack_tag}\n"
+        f"Other pressure angles available: {tags_preview}\n\n"
+        "Open the battle. Ask your first hard question about the startup above. "
+        "Do not introduce yourself. Do not say hello. Go straight to the question. "
+        "Attack the weakest claim in the pitch. Keep it under 3 sentences. "
+        "Ask exactly one question."
+    )
+
+    return [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_content},
+    ]
+
+
+def _build_followup_messages(
+    startup: dict,
+    persona: str,
+    difficulty: str,
+    attack_tag: str,
+    history: list[dict[str, Any]],
+    judge_action: dict[str, Any],
+    answer_quality: dict[str, Any],
+) -> list[dict[str, str]]:
+    """Build the OpenAI-format messages list for a follow-up judge question.
+
+    The prompt instruction varies based on judge_action to guide Nemotron
+    toward the correct Socratic behavior:
+      - follow_up_same_tag  → press harder on the same topic
+      - move_next_tag       → acknowledge prior point, move cleanly
+      - move_after_limit    → briefly flag unresolved point, move on
+
+    Voice mode note:
+      History entries may originate from typed text or voice transcripts.
+      The prompt wording uses "your answer" rather than "you typed" throughout.
+    """
+    system_prompt = build_persona_prompt(persona, startup, difficulty)
+
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": system_prompt},
+    ]
+
+    # Replay conversation history as role turns (strip attack_tag metadata)
+    for entry in history:
+        role = entry.get("role", "user")
+        content = entry.get("content", "")
+        if role == "assistant":
+            messages.append({"role": "assistant", "content": content})
+        else:
+            messages.append({"role": "user", "content": content})
+
+    action = judge_action.get("judge_action", "follow_up_same_tag")
+    prev_tag = judge_action.get("previous_attack_tag", attack_tag)
+    quality = answer_quality.get("quality", "partial")
+    transition = judge_action.get("transition_note", "")
+
+    if action == "follow_up_same_tag":
+        instruction = (
+            f"Attack focus: {attack_tag}\n"
+            f"Your answer was classified as {quality}. {transition}\n\n"
+            "The founder's last answer was insufficient. "
+            "Ask one sharper, more specific follow-up on the SAME topic. "
+            "Reference what they just said directly. "
+            "Do not move to a new topic yet. "
+            "Do not give advice. Do not say 'great answer' or 'interesting.' "
+            "Keep it under 3 sentences. Ask exactly one question."
+        )
+    elif action == "move_next_tag":
+        instruction = (
+            f"New attack focus: {attack_tag}\n"
+            f"Previous topic ({prev_tag}) is considered resolved. Do NOT revisit it.\n\n"
+            "The founder gave a sufficient answer on the previous point. "
+            "Move immediately to the new attack focus above. "
+            "Do not keep drilling the previous topic. "
+            "Do not say 'great answer', 'good point', 'well done', or any praise. "
+            "Do not ask multiple questions. "
+            "Do not give advice. "
+            "Ask exactly one hard, specific question on the new attack focus. "
+            "Keep the entire response under 3 sentences."
+        )
+    else:  # move_after_limit
+        instruction = (
+            f"New attack focus: {attack_tag}\n"
+            f"Previous topic ({prev_tag}) remains unresolved. {transition}\n\n"
+            "Briefly note that the previous issue was not fully addressed — "
+            "one short clause only, then move on. "
+            "Ask one hard question on the new attack focus. "
+            "Do not keep drilling the unresolved point. "
+            "Do not give advice. Keep it under 4 sentences. Ask exactly one question."
+        )
+
+    messages.append({"role": "user", "content": instruction})
+    return messages
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+def handle_start_session(payload: dict[str, Any]) -> dict[str, Any]:
+    """Create a new pitch battle session and return the opening challenge."""
+    startup = payload.get("startup") or {}
+    persona = payload.get("persona", "technical_judge")
+    difficulty = payload.get("difficulty", "high")
+    input_mode = payload.get("input_mode", "text")
+    mode = payload.get("mode", "pitch_battle")
+    model_mode = payload.get("model_mode", "premium_nvidia")
+
+    session = session_manager.create_session(
+        startup, persona, difficulty, input_mode
+    )
+    session["mode"] = mode
+    session["model_mode"] = model_mode
+
+    mock_attack_tag, mock_ai_message = OPENING_MESSAGES.get(
+        persona, OPENING_MESSAGES["technical_judge"]
+    )
+
+    attack_tag = mock_attack_tag
+    ai_message = mock_ai_message
+    model_ok = False
+    provider = "mock"
+    used_model_mode = "mock_fallback"
+    model_error: str | None = None
+
+    try:
+        messages = _build_opening_messages(startup, persona, difficulty, mock_attack_tag)
+        result = model_router.generate_opponent_response(
+            messages,
+            model_mode=model_mode,
+            persona=persona,
+            attack_tag=mock_attack_tag,
+        )
+        if result.get("ok") and result.get("content"):
+            ai_message = sanitize_model_output(result["content"])
+            model_ok = True
+            provider = result.get("provider", "nvidia")
+            used_model_mode = result.get("model_mode", model_mode)
+        else:
+            model_error = result.get("error") or "Model returned empty response"
+            logger.warning("start_session: model not ok — using mock. error=%s", model_error)
+    except Exception as exc:
+        model_error = str(exc)
+        logger.warning("start_session: model call raised — using mock. error=%s", exc)
+
+    # Initialize battle_state with opening tag
+    battle_flow.init_opening_state(session, attack_tag)
+
+    session_manager.append_ai_message(session["session_id"], ai_message, attack_tag)
+
+    return {
+        "session_id": session["session_id"],
+        "round": 1,
+        "pressure_level": pressure_level(1),
+        "battle_phase": get_battle_phase(1),
+        "attack_tag": attack_tag,
+        "ai_message": ai_message,
+        "model_mode": used_model_mode,
+        "provider": provider,
+        "model_ok": model_ok,
+        "judge_action": "opening_question",
+        "answer_quality": None,
+        "topic_satisfied": None,
+        "tag_attempt": 1,
+        "soft_round_limit_reached": False,
+        "battle_complete": False,
+        "can_continue": True,
+        "next_action": "continue",
+        **({"model_error": model_error} if model_error else {}),
+    }
+
+
+def handle_chat_round(payload: dict[str, Any]) -> dict[str, Any]:
+    """Process a user reply and return the next judge question.
+
+    Voice mode note:
+      user_message may be a typed string or a transcript from voice input.
+      battle_flow.classify_answer_quality() handles both the same way.
+    """
+    session_id = payload.get("session_id", "")
+    message = (
+        payload.get("user_message") or payload.get("message") or ""
+    ).strip()
+
+    session = session_manager.get_session(session_id)
+    if not session:
+        return {
+            "session_id": session_id,
+            "error": "Session not found",
+            "round": 0,
+            "pressure_level": "High",
+            "attack_tag": "Session Error",
+            "ai_message": "Session expired. Please start a new battle.",
+            "model_ok": False,
+            "provider": "none",
+            "model_mode": "none",
+        }
+
+    if message:
+        session_manager.append_user_message(session_id, message)
+
+    persona = session.get("persona", "technical_judge")
+    difficulty = session.get("difficulty", "high")
+    startup = session.get("startup", {})
+    model_mode = session.get("model_mode", "premium_nvidia")
+    next_round = session_manager.increment_round(session_id)
+
+    soft_limit = next_round >= MAX_ROUNDS
+
+    # Determine current attack tag from last AI message
+    current_attack_tag = battle_flow.get_current_attack_tag(session)
+    if not current_attack_tag:
+        current_attack_tag = get_next_attack_tag(persona, next_round)
+
+    # Classify answer quality (rule-based, no extra API call)
+    answer_quality_result = {"quality": "partial", "reason": "No message provided.", "signals": []}
+    if message:
+        try:
+            answer_quality_result = battle_flow.classify_answer_quality(message)
+        except Exception as exc:
+            logger.warning("battle_flow.classify_answer_quality error: %s", exc)
+
+    quality = answer_quality_result.get("quality", "partial")
+
+    # Decide judge action
+    judge_action_result: dict[str, Any] = {}
+    try:
+        judge_action_result = battle_flow.decide_next_judge_action(
+            session, current_attack_tag, quality, persona
+        )
+    except Exception as exc:
+        logger.warning("battle_flow.decide_next_judge_action error: %s", exc)
+        judge_action_result = {
+            "judge_action": "follow_up_same_tag",
+            "next_attack_tag": current_attack_tag,
+            "previous_attack_tag": current_attack_tag,
+            "attempt_number_for_tag": 1,
+            "topic_satisfied": False,
+            "transition_note": "Fallback due to decision error.",
+        }
+
+    # Update session battle state
+    try:
+        battle_flow.update_battle_state(session, current_attack_tag, answer_quality_result, judge_action_result)
+    except Exception as exc:
+        logger.warning("battle_flow.update_battle_state error: %s", exc)
+
+    attack_tag = judge_action_result.get("next_attack_tag", current_attack_tag)
+
+    # Mock fallback
+    followups = MOCK_FOLLOWUPS.get(persona, MOCK_FOLLOWUPS["technical_judge"])
+    index = min(next_round - 2, len(followups) - 1)
+    mock_ai_message = followups[max(0, index)]
+
+    ai_message = mock_ai_message
+    model_ok = False
+    provider = "mock"
+    used_model_mode = "mock_fallback"
+    model_error: str | None = None
+
+    try:
+        # Cap history sent to model; full history preserved in session for scorecard
+        recent_history = _recent_history(session_id)
+        messages = _build_followup_messages(
+            startup,
+            persona,
+            difficulty,
+            attack_tag,
+            recent_history,
+            judge_action_result,
+            answer_quality_result,
+        )
+        result = model_router.generate_opponent_response(
+            messages,
+            model_mode=model_mode,
+            persona=persona,
+            attack_tag=attack_tag,
+        )
+        if result.get("ok") and result.get("content"):
+            ai_message = sanitize_model_output(result["content"])
+            model_ok = True
+            provider = result.get("provider", "nvidia")
+            used_model_mode = result.get("model_mode", model_mode)
+        else:
+            model_error = result.get("error") or "Model returned empty response"
+            logger.warning("chat_round: model not ok — using mock. error=%s", model_error)
+    except Exception as exc:
+        model_error = str(exc)
+        logger.warning("chat_round: model call raised — using mock. error=%s", exc)
+
+    session_manager.append_ai_message(session_id, ai_message, attack_tag)
+
+    return {
+        "session_id": session_id,
+        "round": next_round,
+        "pressure_level": pressure_level(next_round),
+        "battle_phase": get_battle_phase(next_round),
+        "attack_tag": attack_tag,
+        "ai_message": ai_message,
+        "model_mode": used_model_mode,
+        "provider": provider,
+        "model_ok": model_ok,
+        "answer_quality": quality,
+        "answer_quality_reason": answer_quality_result.get("reason", ""),
+        "judge_action": judge_action_result.get("judge_action", "follow_up_same_tag"),
+        "previous_attack_tag": judge_action_result.get("previous_attack_tag", current_attack_tag),
+        "topic_satisfied": judge_action_result.get("topic_satisfied", False),
+        "tag_attempt": judge_action_result.get("attempt_number_for_tag", 1),
+        "battle_complete": False,
+        "can_continue": True,
+        "next_action": "continue",
+        "soft_round_limit_reached": soft_limit,
+        "rounds_soft_limit_reached": soft_limit,
+        "recommended_action": "end_battle" if soft_limit else None,
+        "completion_message": (
+            "You have enough material for a scorecard. You can end the battle now or continue practicing."
+            if soft_limit else None
+        ),
+        **({"model_error": model_error} if model_error else {}),
+    }
+
+
+def handle_end_battle(payload: dict[str, Any]) -> dict[str, Any]:
+    """Generate and return a Nemotron scorecard for the completed battle.
+
+    Falls back to mock_scorecard if the model call or JSON parsing fails.
+    Never crashes for a valid session.
+
+    Voice mode note:
+        Session history contains plain text regardless of input source.
+        No changes are needed here when voice mode is integrated.
+    """
+    session_id = payload.get("session_id", "")
+    session = session_manager.get_session(session_id)
+    if not session:
+        return {"error": "Session not found"}
+
+    try:
+        scorecard = generate_claim_based_scorecard(session)
+    except Exception as exc:
+        logger.warning("handle_end_battle: generate_claim_based_scorecard raised: %s", exc)
+        try:
+            signals = extract_concrete_signals(session)
+            scorecard = build_session_aware_fallback_scorecard(
+                session, signals, f"Scorecard generation error: {type(exc).__name__}"
+            )
+        except Exception as exc2:
+            logger.warning("handle_end_battle: session-aware fallback also raised: %s", exc2)
+            scorecard = mock_scorecard(session)
+            scorecard["model_error"] = f"Scorecard generation error: {type(exc).__name__}"
+
+    return scorecard
+
+
+def handle_reset_session(payload: dict[str, Any]) -> dict[str, Any]:
+    """Clear a battle session."""
+    session_id = payload.get("session_id", "")
+    session_manager.reset_session(session_id)
+    return {"status": "reset"}
+
+
+def handle_voice_pitch_placeholder(_payload: dict[str, Any] | None = None) -> dict[str, str]:
+    """Reserved endpoint for voice pitch mode."""
+    return {
+        "status": "not_implemented",
+        "message": (
+            "Voice Mode endpoint is reserved and will be connected "
+            "after transcription integration."
+        ),
+    }
+
+
+def handle_deal_session_placeholder(_payload: dict[str, Any] | None = None) -> dict[str, str]:
+    """Reserved endpoint for Deal Battle mode."""
+    return {
+        "status": "not_implemented",
+        "message": (
+            "Deal Battle endpoint is reserved and will be connected "
+            "in a later phase."
+        ),
+    }
+
+
+def handle_deck_critique_placeholder(_payload: dict[str, Any] | None = None) -> dict[str, str]:
+    """Reserved endpoint for pitch deck critique."""
+    return {
+        "status": "not_implemented",
+        "message": (
+            "Deck critique endpoint is reserved and will be connected "
+            "after MiniCPM-V vision integration."
+        ),
+    }

core/attack_tags.py

@@ -0,0 +1,50 @@
+"""Attack tag taxonomy and round-based tag selection."""
+
+from __future__ import annotations
+
+ATTACK_TAGS: dict[str, list[str]] = {
+    "skeptical_vc": [
+        "Market Size",
+        "Moat",
+        "Retention",
+        "Revenue Logic",
+        "First 100 Users",
+        "Why Now",
+        "Competition",
+        "Defensibility",
+    ],
+    "technical_judge": [
+        "AI Justification",
+        "Architecture",
+        "Scalability",
+        "Latency",
+        "Data Quality",
+        "Failure Mode",
+        "Simpler Alternative",
+        "Technical Feasibility",
+    ],
+    "hackathon_judge": [
+        "Novelty",
+        "Demo Clarity",
+        "MVP Strength",
+        "User Pain",
+        "AI Load-Bearing",
+        "Backyard Fit",
+        "Practical Impact",
+        "Judging Memorability",
+    ],
+}
+
+
+def get_attack_tags(persona: str) -> list[str]:
+    """Return attack tags for a persona."""
+    return list(ATTACK_TAGS.get(persona, ATTACK_TAGS["technical_judge"]))
+
+
+def get_next_attack_tag(persona: str, round_number: int) -> str:
+    """Pick the next attack tag based on persona and round (1-indexed)."""
+    tags = get_attack_tags(persona)
+    if not tags:
+        return "General Pressure"
+    index = max(0, round_number - 1) % len(tags)
+    return tags[index]

core/battle_flow.py

@@ -0,0 +1,301 @@
+"""Battle flow controller for PitchFight AI.
+
+Controls Socratic judge pacing:
+- Classifies each founder answer (strong / partial / weak / non_answer)
+- Decides whether to follow up on the same attack tag or move to the next one
+- Enforces MAX_ATTEMPTS_PER_ATTACK_TAG so no topic is drilled forever
+- Maintains per-session battle state (tag_attempts, outcomes, completed_tags)
+
+Voice mode note:
+  Future voice mode will pass transcripts into the same classify_answer_quality()
+  and decide_next_judge_action() functions without any changes here.
+  This module never assumes keyboard input — it only sees text strings.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from core.attack_tags import get_attack_tags
+
+MAX_ATTEMPTS_PER_ATTACK_TAG = 2
+MAX_FOLLOWUPS_PER_ATTACK_TAG = 1  # same as attempts - 1 (first is always a fresh question)
+
+# ---------------------------------------------------------------------------
+# Weak-signal patterns (rule-based, no extra API call)
+# ---------------------------------------------------------------------------
+
+_NON_ANSWER_PHRASES = {
+    "ok", "okay", "idk", "i don't know", "dont know", "don't know",
+    "not sure", "maybe", "no idea", "hmm", "i'm not sure", "im not sure",
+    "i dont know", "i have no idea", "not really", "yeah", "sure",
+    "fine", "alright", "whatever", "pass",
+}
+
+_VAGUE_WORDS = {
+    "big", "huge", "large", "massive", "many", "everyone", "anybody",
+    "helpful", "useful", "better", "good", "great", "nice", "amazing",
+    "smart", "intelligent", "automatically", "seamlessly", "easily",
+    "quickly", "simply", "pretty", "kind", "sort", "basically",
+    "generally", "typically", "usually", "obviously", "clearly",
+}
+
+_STRONG_SIGNALS = [
+    # Concrete numbers attached to evidence nouns
+    r"\d+\s*%",                                                                      # 12%
+    r"\d+\s*\w*\s*(users?|signups?|students?|schools?|campuses?|installs?|teams?|pilots?|ambassadors?|colleges?|universities)",
+    r"\$\s*\d+",                                                                     # $50
+    r"\d+\s*(k|m|b)\b",                                                             # 10k, 2m
+    # Product and business metrics
+    r"\b(dau|mau|wau|retention|churn|ltv|arpu|cac|nps)\b",
+    r"\b(paying|waitlist|revenue|traction|mrr|arr)\b",
+    # User research and validation
+    r"\b(interviewed|surveyed|measured|validated|tested|piloted)\b",
+    r"\b(user interview|data point|conversion rate|event.miss report)\b",
+    # Named target segment (specific, not vague "everyone")
+    r"\b(cs students?|engineering students?|stem students?|mba students?|undergrad|sophomore|freshman|senior year)\b",
+    r"\b(iit|nit|bits|vit|college name|university name)\b",
+    # Competitor differentiation
+    r"\b(unlike\s+\w+|vs\.?\s+\w+|compared to\s+\w+|instead of\s+\w+|luma|lu\.ma|eventbrite|meetup|devfolio|unstop)\b",
+    # Revenue or retention logic
+    r"\b(monthly recurring|annual recurring|subscription|freemium|pay per|sponsor pays|college pays)\b",
+    # Specific technical explanation (more than buzzwords)
+    r"\b(embedding|vector|fine.?tun|retrieval|ranking model|cosine similarity|recommendation engine)\b",
+]
+
+_STRONG_PATTERN = re.compile(
+    "|".join(_STRONG_SIGNALS),
+    re.IGNORECASE,
+)
+
+
+def classify_answer_quality(answer: str) -> dict[str, Any]:
+    """Classify a founder answer without making any API calls.
+
+    Voice mode note:
+      Accepts text from any source — typed input or voice transcript.
+      The caller is responsible for converting audio to text before calling here.
+
+    Returns:
+        {
+            "quality":  "strong" | "partial" | "weak" | "non_answer",
+            "reason":   human-readable explanation,
+            "signals":  list of matched evidence signals (may be empty),
+        }
+    """
+    text = answer.strip()
+    words = text.split()
+    word_count = len(words)
+    lower = text.lower()
+
+    # --- non_answer: empty, trivially short, or known filler phrase ---
+    if word_count < 4:
+        return {
+            "quality": "non_answer",
+            "reason": "Answer is too short to evaluate.",
+            "signals": [],
+        }
+
+    if lower in _NON_ANSWER_PHRASES or any(
+        lower.startswith(p) or lower == p for p in _NON_ANSWER_PHRASES
+    ):
+        return {
+            "quality": "non_answer",
+            "reason": "Answer is a known non-response phrase.",
+            "signals": [],
+        }
+
+    # --- strong: contains concrete evidence signals ---
+    strong_hits = [m.group(0) for m in _STRONG_PATTERN.finditer(text)]
+    if strong_hits:
+        unique = list({h.strip().lower() for h in strong_hits if h.strip()})
+        return {
+            "quality": "strong",
+            "reason": "Answer contains concrete evidence or data.",
+            "signals": unique[:5],
+        }
+
+    # --- weak: short or dominated by vague terms ---
+    lower_words = set(re.findall(r"\w+", lower))
+    vague_overlap = lower_words & _VAGUE_WORDS
+    vague_count = len(vague_overlap)
+    vague_ratio = vague_count / max(word_count, 1)
+
+    # A sentence is weak if it's short, has a high vague ratio,
+    # OR contains 2+ vague adjectives that carry the main claim
+    is_weak = word_count < 8 or vague_ratio >= 0.20 or (vague_count >= 2 and word_count < 20)
+
+    if is_weak:
+        return {
+            "quality": "weak",
+            "reason": (
+                "Answer is too short or relies on vague claims without evidence."
+                + (f" Vague words: {', '.join(sorted(vague_overlap)[:3])}." if vague_overlap else "")
+            ),
+            "signals": [],
+        }
+
+    # --- partial: answer has some content but no strong signals ---
+    return {
+        "quality": "partial",
+        "reason": "Answer gives some reasoning but lacks concrete evidence or numbers.",
+        "signals": [],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Battle state helpers
+# ---------------------------------------------------------------------------
+
+def _init_battle_state(session: dict) -> dict:
+    """Return existing battle_state or create a fresh one."""
+    if "battle_state" not in session:
+        session["battle_state"] = {
+            "tag_attempts": {},      # {attack_tag: int}
+            "tag_outcomes": {},      # {attack_tag: "resolved" | "unresolved"}
+            "last_answer_quality": {},
+            "last_judge_action": {},
+            "completed_tags": [],
+        }
+    return session["battle_state"]
+
+
+def init_opening_state(session: dict, opening_attack_tag: str) -> None:
+    """Initialize battle_state at session start with the opening tag attempt."""
+    state = _init_battle_state(session)
+    state["tag_attempts"][opening_attack_tag] = 1
+    state["last_judge_action"] = {
+        "judge_action": "opening_question",
+        "next_attack_tag": opening_attack_tag,
+        "previous_attack_tag": None,
+        "attempt_number_for_tag": 1,
+        "topic_satisfied": None,
+        "transition_note": "Opening question.",
+    }
+
+
+def decide_next_judge_action(
+    session: dict,
+    current_attack_tag: str,
+    answer_quality: str,
+    persona: str,
+) -> dict[str, Any]:
+    """Decide what the judge should do next based on answer quality and tag history.
+
+    Returns:
+        {
+            "judge_action":           "follow_up_same_tag" | "move_next_tag" | "move_after_limit",
+            "next_attack_tag":        str,
+            "previous_attack_tag":    str,
+            "attempt_number_for_tag": int,
+            "topic_satisfied":        bool,
+            "transition_note":        str,
+        }
+    """
+    state = _init_battle_state(session)
+    tag_attempts: dict[str, int] = state.get("tag_attempts", {})
+
+    current_attempts = tag_attempts.get(current_attack_tag, 1)
+
+    # --- Strong answer: topic done, advance ---
+    if answer_quality == "strong":
+        state["tag_outcomes"][current_attack_tag] = "resolved"
+        if current_attack_tag not in state["completed_tags"]:
+            state["completed_tags"].append(current_attack_tag)
+
+        next_tag = _pick_next_tag(persona, state)
+        tag_attempts[next_tag] = tag_attempts.get(next_tag, 0) + 1
+
+        return {
+            "judge_action": "move_next_tag",
+            "next_attack_tag": next_tag,
+            "previous_attack_tag": current_attack_tag,
+            "attempt_number_for_tag": tag_attempts[next_tag],
+            "topic_satisfied": True,
+            "transition_note": (
+                f"Founder addressed {current_attack_tag} adequately. Moving to {next_tag}."
+            ),
+        }
+
+    # --- Weak / partial / non_answer ---
+    if current_attempts < MAX_ATTEMPTS_PER_ATTACK_TAG:
+        # Follow up on the same tag
+        tag_attempts[current_attack_tag] = current_attempts + 1
+
+        return {
+            "judge_action": "follow_up_same_tag",
+            "next_attack_tag": current_attack_tag,
+            "previous_attack_tag": current_attack_tag,
+            "attempt_number_for_tag": current_attempts + 1,
+            "topic_satisfied": False,
+            "transition_note": (
+                f"Answer was {answer_quality}. Pressing harder on {current_attack_tag} "
+                f"(attempt {current_attempts + 1}/{MAX_ATTEMPTS_PER_ATTACK_TAG})."
+            ),
+        }
+
+    # --- Limit reached: mark unresolved, move on ---
+    state["tag_outcomes"][current_attack_tag] = "unresolved"
+    if current_attack_tag not in state["completed_tags"]:
+        state["completed_tags"].append(current_attack_tag)
+
+    next_tag = _pick_next_tag(persona, state)
+    tag_attempts[next_tag] = tag_attempts.get(next_tag, 0) + 1
+
+    return {
+        "judge_action": "move_after_limit",
+        "next_attack_tag": next_tag,
+        "previous_attack_tag": current_attack_tag,
+        "attempt_number_for_tag": tag_attempts[next_tag],
+        "topic_satisfied": False,
+        "transition_note": (
+            f"Max attempts reached for {current_attack_tag} — moving to {next_tag}."
+        ),
+    }
+
+
+def update_battle_state(
+    session: dict,
+    attack_tag: str,
+    answer_quality: dict[str, Any],
+    judge_action: dict[str, Any],
+) -> dict[str, Any]:
+    """Persist answer quality and judge action into session battle_state."""
+    state = _init_battle_state(session)
+    state["last_answer_quality"] = answer_quality
+    state["last_judge_action"] = judge_action
+    return state
+
+
+def get_current_attack_tag(session: dict) -> str | None:
+    """Return the attack tag from the last AI message stored in history."""
+    history = session.get("history", [])
+    for entry in reversed(history):
+        if entry.get("role") == "assistant" and entry.get("attack_tag"):
+            return entry["attack_tag"]
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Internal: pick the next tag not yet exhausted
+# ---------------------------------------------------------------------------
+
+def _pick_next_tag(persona: str, state: dict) -> str:
+    """Select the next attack tag, preferring unused ones."""
+    all_tags = get_attack_tags(persona)
+    tag_attempts: dict[str, int] = state.get("tag_attempts", {})
+    completed: list[str] = state.get("completed_tags", [])
+
+    # Prefer tags not yet attempted
+    for tag in all_tags:
+        if tag not in tag_attempts:
+            return tag
+
+    # Fall back to tags with lowest attempts that aren't in completed
+    remaining = [t for t in all_tags if t not in completed]
+    if remaining:
+        return min(remaining, key=lambda t: tag_attempts.get(t, 0))
+
+    # All tags exhausted — cycle from the beginning
+    return all_tags[0] if all_tags else "General Pressure"

core/claim_extractor.py

@@ -0,0 +1,274 @@
+"""Concrete claim and signal extractor for PitchFight AI scorecard.
+
+Extracts evidence signals from founder answers using regex/rule-based logic.
+No API calls — fast, local, deterministic.
+
+Used by scoring_engine.py to:
+  1. Enrich the Nemotron scoring prompt with pre-extracted signal data
+  2. Build session-aware fallback scorecards when model scoring fails
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Compiled patterns
+# ---------------------------------------------------------------------------
+
+_NUMBER_METRIC = re.compile(
+    r"\b\d[\d,]*\.?\d*\s*"
+    r"(?:%|percent|users?|students?|signups?|schools?|campuses?|"
+    r"colleges?|installs?|ambassadors?|interviews?|pilots?|teams?|"
+    r"paying|members?|founders?|customers?|clients?|respondents?|"
+    r"participants?|responses?)\b"
+    r"|\b\d[\d,]+\b",
+    re.IGNORECASE,
+)
+
+_PERCENTAGE = re.compile(
+    r"\b\d+\.?\d*\s*%|\b\d+\.?\d*\s*percent\b",
+    re.IGNORECASE,
+)
+
+_CURRENCY = re.compile(
+    r"[₹$€£¥]\s*\d[\d,.]*"
+    r"|\b\d[\d,.]*\s*(?:rupees?|dollars?|usd|inr|cad|euros?)\b"
+    r"|\brs\.?\s*\d[\d,.]*\b",
+    re.IGNORECASE,
+)
+
+_USER_COUNT = re.compile(
+    r"\b\d+\s*(?:beta\s+)?users?\b"
+    r"|\b\d+\s*(?:beta\s+)?signups?\b"
+    r"|\b\d+\s*students?\b"
+    r"|\b\d+\s*members?\b"
+    r"|\b\d+\s*paying\b"
+    r"|\b\d+\s*customers?\b",
+    re.IGNORECASE,
+)
+
+_VALIDATION = re.compile(
+    r"\b(?:beta|pilot|prototype|mvp|tested|validated|launched|surveyed|"
+    r"interviewed|user research|focus group|waitlist|signups?|onboarding|"
+    r"usability test|field test|user test|a/b test|experiment)\b"
+    r"|\bevent.?miss reports?\b"
+    r"|\bcampus ambassadors?\b",
+    re.IGNORECASE,
+)
+
+_COLLEGE_CAMPUS = re.compile(
+    r"\b(?:campus(?:es)?|colleges?|universities|university|iit|nit|bits|vit|"
+    r"mit|stanford|oxford|ambassadors?|chapters?)\b",
+    re.IGNORECASE,
+)
+
+_COMPETITORS = re.compile(
+    r"\b(?:luma|lu\.ma|eventbrite|devfolio|unstop|meetup|linkedin|facebook|"
+    r"whatsapp|google|notion|airtable|twitter|x\.com|slack|discord|"
+    r"internshala|naukri|glassdoor|monster)\b"
+    r"|\b(?:competitors?|alternatives?)\b"
+    r"|\bunlike\s+\w+\b"
+    r"|\bvs\.?\s+\w+\b",
+    re.IGNORECASE,
+)
+
+_TECH_MECHANISM = re.compile(
+    r"\b(?:embedding|vector|fine.?tun|retrieval|ranking model|cosine similarity|"
+    r"recommendation engine|nlp|llm|transformer|gpt|bert|neural|classifier|"
+    r"semantic search|knowledge graph|rag|inference|profile matching|"
+    r"skill.based|personali[sz]ation|latency|throughput|model|algorithm|"
+    r"api|webhook|scraping|crawler|pipeline)\b",
+    re.IGNORECASE,
+)
+
+_REVENUE = re.compile(
+    r"\b(?:revenue|mrr|arr|subscription|freemium|pay per|college pays|"
+    r"sponsor pays|b2b|b2c|saas|monetize|price|pricing|charge|conversion|"
+    r"cac|ltv|arpu|monthly plan|annual plan|tier|upsell|markup|margin|"
+    r"transaction fee|commission|licensing|enterprise)\b",
+    re.IGNORECASE,
+)
+
+_RETENTION = re.compile(
+    r"\b(?:retention|churn|dau|mau|wau|weekly active|daily active|"
+    r"returning users?|re.engagement|habit|repeat|sticky|lock.in|"
+    r"notification|reminder|follow.?up|engagement rate)\b",
+    re.IGNORECASE,
+)
+
+_GTM = re.compile(
+    r"\b(?:gtm|go.to.market|acquisition|channel|referral|viral|"
+    r"word.of.mouth|ambassador|campus rep|partnership|integration|"
+    r"distribution|onboard|launch|rollout|phase\s*\d)\b",
+    re.IGNORECASE,
+)
+
+_VAGUE_PHRASES = re.compile(
+    r"\bbig market\b|\bhuge market\b|\blarge market\b"
+    r"|\beveryone\b|\banybody\b"
+    r"|\buseful for\b|\bhelpful for\b|\bgood for\b|\bgreat for\b"
+    r"|\bai will\b|\bai can\b"
+    r"|\bautomatically\b|\bseamlessly\b|\beasily\b|\bquickly\b"
+    r"|\bbasically\b|\bgenerally\b|\btypically\b|\bobviously\b",
+    re.IGNORECASE,
+)
+
+_NON_ANSWER_EXACT: frozenset[str] = frozenset({
+    "ok", "okay", "idk", "i don't know", "dont know", "don't know",
+    "not sure", "maybe", "no idea", "hmm", "i'm not sure", "im not sure",
+    "i dont know", "i have no idea", "not really", "yeah", "sure",
+    "fine", "alright", "whatever", "pass", "i'll think about it",
+    "we'll figure it out", "good question",
+})
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _match_all(pattern: re.Pattern, text: str) -> list[str]:
+    return [m.group(0).strip() for m in pattern.finditer(text)]
+
+
+def _dedup(lst: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in lst:
+        key = item.lower().strip()
+        if key and key not in seen:
+            seen.add(key)
+            out.append(item)
+    return out
+
+
+def _is_non_answer(text: str) -> bool:
+    stripped = text.strip().lower()
+    if not stripped or len(stripped.split()) < 4:
+        return True
+    return stripped in _NON_ANSWER_EXACT or any(
+        stripped.startswith(p) for p in _NON_ANSWER_EXACT
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main extractor
+# ---------------------------------------------------------------------------
+
+def extract_concrete_signals(session: dict) -> dict[str, Any]:
+    """Extract evidence signals from all user turns in a session.
+
+    Processes only user-role messages. No API calls.
+
+    Returns:
+        {
+            "numbers":              list[str],   # raw number matches
+            "percentages":          list[str],
+            "pricing":              list[str],   # currency amounts
+            "user_counts":          list[str],   # "50 beta users", etc.
+            "validation":           list[str],   # tested / piloted / surveyed
+            "college_mentions":     list[str],   # campus / college / IIT etc.
+            "competitors":          list[str],   # named competitors
+            "technical_mechanisms": list[str],   # embedding / ranking model etc.
+            "revenue_signals":      list[str],   # subscription / pricing / CAC
+            "retention_signals":    list[str],   # churn / DAU / retention
+            "gtm_signals":          list[str],   # referral / ambassador / launch
+            "non_answers":          list[str],   # evasion/non-answer turns
+            "vague_claims":         list[str],   # buzzword phrases
+            "best_user_quotes":     list[str],   # up to 5 most signal-dense answers
+            "all_user_answers":     list[str],   # every user message
+            "signal_count":         int,         # total unique signals found
+        }
+    """
+    history = session.get("history", [])
+    user_answers = [
+        e["content"].strip()
+        for e in history
+        if e.get("role") == "user" and e.get("content", "").strip()
+    ]
+
+    all_numbers: list[str] = []
+    all_pct: list[str] = []
+    all_pricing: list[str] = []
+    all_user_counts: list[str] = []
+    all_validation: list[str] = []
+    all_colleges: list[str] = []
+    all_competitors: list[str] = []
+    all_tech: list[str] = []
+    all_revenue: list[str] = []
+    all_retention: list[str] = []
+    all_gtm: list[str] = []
+    all_vague: list[str] = []
+    non_answer_turns: list[str] = []
+    answer_scores: list[tuple[int, str]] = []
+
+    for ans in user_answers:
+        if _is_non_answer(ans):
+            non_answer_turns.append(ans)
+            answer_scores.append((0, ans))
+            continue
+
+        nums    = _match_all(_NUMBER_METRIC, ans)
+        pcts    = _match_all(_PERCENTAGE, ans)
+        prices  = _match_all(_CURRENCY, ans)
+        ucounts = _match_all(_USER_COUNT, ans)
+        val     = _match_all(_VALIDATION, ans)
+        cols    = _match_all(_COLLEGE_CAMPUS, ans)
+        comps   = _match_all(_COMPETITORS, ans)
+        techs   = _match_all(_TECH_MECHANISM, ans)
+        revs    = _match_all(_REVENUE, ans)
+        rets    = _match_all(_RETENTION, ans)
+        gtms    = _match_all(_GTM, ans)
+        vagues  = _match_all(_VAGUE_PHRASES, ans)
+
+        all_numbers.extend(nums)
+        all_pct.extend(pcts)
+        all_pricing.extend(prices)
+        all_user_counts.extend(ucounts)
+        all_validation.extend(val)
+        all_colleges.extend(cols)
+        all_competitors.extend(comps)
+        all_tech.extend(techs)
+        all_revenue.extend(revs)
+        all_retention.extend(rets)
+        all_gtm.extend(gtms)
+        all_vague.extend(vagues)
+
+        # Signal density score for ranking quotes
+        density = (
+            len(nums) + len(pcts) + len(prices) + len(ucounts) +
+            len(val) + len(cols) + len(comps) + len(techs) + len(revs)
+        )
+        answer_scores.append((density, ans))
+
+    # Sort by density descending; take top 5 non-trivial answers
+    sorted_answers = sorted(answer_scores, key=lambda x: x[0], reverse=True)
+    best_quotes = [ans for score, ans in sorted_answers if score > 0][:5]
+
+    total_signals = (
+        len(_dedup(all_numbers)) + len(_dedup(all_pct)) +
+        len(_dedup(all_pricing)) + len(_dedup(all_user_counts)) +
+        len(_dedup(all_validation)) + len(_dedup(all_colleges)) +
+        len(_dedup(all_competitors)) + len(_dedup(all_tech)) +
+        len(_dedup(all_revenue))
+    )
+
+    return {
+        "numbers":               _dedup(all_numbers),
+        "percentages":           _dedup(all_pct),
+        "pricing":               _dedup(all_pricing),
+        "user_counts":           _dedup(all_user_counts),
+        "validation":            _dedup(all_validation),
+        "college_mentions":      _dedup(all_colleges),
+        "competitors":           _dedup(all_competitors),
+        "technical_mechanisms":  _dedup(all_tech),
+        "revenue_signals":       _dedup(all_revenue),
+        "retention_signals":     _dedup(all_retention),
+        "gtm_signals":           _dedup(all_gtm),
+        "non_answers":           non_answer_turns,
+        "vague_claims":          _dedup(all_vague),
+        "best_user_quotes":      best_quotes,
+        "all_user_answers":      user_answers,
+        "signal_count":          total_signals,
+    }

core/feedback_generator.py

@@ -0,0 +1,41 @@
+"""Placeholder feedback generators for Phase 1 mock responses."""
+
+from __future__ import annotations
+
+
+def generate_improved_answer(weak_answer: str, startup: dict) -> str:
+    """Return a stronger mock rewrite for a weak founder answer."""
+    name = startup.get("name", "the product")
+    return (
+        f"Instead of staying vague, anchor your answer in specifics: "
+        f"'{name}' solves a concrete discovery problem for students by ranking events against "
+        f"skills, deadlines, and location — not just aggregating listings. "
+        f"We already tested ranking logic on scraped campus events and saw students shortlist "
+        f"3x faster than browsing WhatsApp groups.' "
+        f"(Your original answer was too thin: \"{weak_answer[:120]}...\")"
+        if len(weak_answer) > 120
+        else (
+            f"Lead with proof: '{name}' matches events to student profiles using skills, goals, "
+            f"and urgency — we validated this with a prototype on real campus event data. "
+            f"Your answer needed more specificity than: \"{weak_answer}\""
+        )
+    )
+
+
+def generate_improved_pitch(startup: dict) -> str:
+    """Return a mock 60-second pitch rewrite."""
+    name = startup.get("name", "Our startup")
+    problem = startup.get("problem", "a real student pain point")
+    solution = startup.get("solution", "a focused product")
+    why_ai = startup.get("why_ai", "intelligent matching")
+    traction = startup.get("traction", "early prototype traction")
+    ask = startup.get("ask", "feedback and support")
+
+    return (
+        f"{name} helps student founders stop missing the events that actually matter. "
+        f"The problem is simple: {problem} "
+        f"Our solution: {solution} "
+        f"AI is load-bearing because {why_ai} "
+        f"Traction so far: {traction} "
+        f"We're asking for {ask}."
+    )

core/json_utils.py

@@ -0,0 +1,192 @@
+"""JSON parsing utilities with safe fallbacks."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def extract_json_block(text: str) -> str | None:
+    """Extract the first JSON object or array block from text."""
+    if not text:
+        return None
+
+    fenced = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", text, re.IGNORECASE)
+    if fenced:
+        return fenced.group(1).strip()
+
+    for opener, closer in (("{", "}"), ("[", "]")):
+        start = text.find(opener)
+        if start == -1:
+            continue
+        depth = 0
+        for index in range(start, len(text)):
+            char = text[index]
+            if char == opener:
+                depth += 1
+            elif char == closer:
+                depth -= 1
+                if depth == 0:
+                    return text[start : index + 1]
+    return None
+
+
+def safe_json_parse(text: str, default: Any = None) -> Any:
+    """Parse JSON from raw text, attempting block extraction on failure."""
+    if default is None:
+        default = {}
+
+    if not text:
+        return default
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        block = extract_json_block(text)
+        if not block:
+            return default
+        try:
+            return json.loads(block)
+        except json.JSONDecodeError:
+            return default
+
+
+def fallback_scorecard() -> dict[str, Any]:
+    """Return a minimal scorecard when model JSON parsing fails."""
+    return {
+        "overall": 0,
+        "scores": {},
+        "best_answer": "No scorecard could be generated.",
+        "weakest_answer": "",
+        "improved_answer": "",
+        "improved_pitch": "",
+        "top_3_questions": [],
+    }
+
+
+_REQUIRED_SCORECARD_DIMS = {
+    "clarity",
+    "problem_understanding",
+    "market_awareness",
+    "differentiation",
+    "business_model",
+    "objection_handling",
+}
+
+
+def _coerce_score(value: Any) -> int:
+    """Clamp a raw score value to integer 0–100."""
+    try:
+        return max(0, min(100, int(float(value))))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _score_label(score: int) -> str:
+    """Map an integer score 0–100 to a human-readable label.
+
+    Phase 5C bands (claim-based calibration):
+      0–30:   Not addressed
+      31–50:  Developing
+      51–70:  Solid
+      71–85:  Strong
+      86–100: Excellent
+    """
+    if score <= 30:
+        return "Not addressed"
+    if score <= 50:
+        return "Developing"
+    if score <= 70:
+        return "Solid"
+    if score <= 85:
+        return "Strong"
+    return "Excellent"
+
+
+def _validate_dim(raw: Any) -> dict[str, Any]:
+    """Normalise a raw score dimension into {score, label, reason, quote, signals_used}."""
+    if not isinstance(raw, dict):
+        return {
+            "score": 0,
+            "label": _score_label(0),
+            "reason": "No data.",
+            "quote": "",
+            "signals_used": [],
+        }
+    score = _coerce_score(raw.get("score", 0))
+    raw_signals = raw.get("signals_used", [])
+    signals = (
+        [str(s).strip() for s in raw_signals if str(s).strip()]
+        if isinstance(raw_signals, list)
+        else []
+    )
+    return {
+        "score": score,
+        "label": _score_label(score),
+        "reason": str(raw.get("reason", "")).strip() or "No reasoning provided.",
+        "quote": str(raw.get("quote", "")).strip(),
+        "signals_used": signals[:8],
+    }
+
+
+def parse_scorecard_json(raw_text: str) -> dict[str, Any] | None:
+    """Parse and validate Nemotron scorecard JSON.
+
+    Fallback order:
+      1. json.loads(raw_text)
+      2. extract_json_block → json.loads
+      3. safe_json_parse
+
+    Returns a validated dict with all required keys, or None if parsing fails
+    completely so the caller can fall back to mock_scorecard.
+
+    Voice mode note:
+      This function is input-source agnostic — it receives only the text
+      output from the model and does not need to change for voice mode.
+    """
+    parsed = safe_json_parse(raw_text)
+    if not parsed or not isinstance(parsed, dict):
+        return None
+
+    # Validate and normalise scores dict
+    raw_scores = parsed.get("scores", {})
+    if not isinstance(raw_scores, dict):
+        raw_scores = {}
+
+    scores: dict[str, Any] = {}
+    for dim in _REQUIRED_SCORECARD_DIMS:
+        scores[dim] = _validate_dim(raw_scores.get(dim))
+
+    # overall: prefer explicit field, else average of dimension scores
+    if "overall" in parsed and parsed["overall"] is not None:
+        overall = _coerce_score(parsed["overall"])
+    else:
+        dim_scores = [scores[d]["score"] for d in _REQUIRED_SCORECARD_DIMS]
+        overall = round(sum(dim_scores) / len(dim_scores)) if dim_scores else 0
+
+    def _str(key: str, default: str = "") -> str:
+        return str(parsed.get(key, default)).strip() or default
+
+    def _list_of_str(key: str) -> list[str]:
+        val = parsed.get(key, [])
+        if isinstance(val, list):
+            return [str(v).strip() for v in val if str(v).strip()]
+        return []
+
+    top_3 = _list_of_str("top_3_questions")[:3]
+    # Pad to 3 if model returned fewer
+    while len(top_3) < 3:
+        top_3.append("What concrete evidence do you have to support this claim?")
+
+    return {
+        "overall": overall,
+        "overall_label": _score_label(overall),
+        "scores": scores,
+        "best_answer": _str("best_answer", "Not identified."),
+        "weakest_answer": _str("weakest_answer", "Not identified."),
+        "why_weak": _str("why_weak", ""),
+        "improved_answer": _str("improved_answer", ""),
+        "improved_pitch": _str("improved_pitch", ""),
+        "top_3_questions": top_3,
+    }

core/local_text_model.py

@@ -0,0 +1,30 @@
+"""Placeholder local text model for Phase 2 integration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class LocalTextModel:
+    """Stub for the future local MiniCPM-family model runtime."""
+
+    def __init__(self) -> None:
+        self.loaded = False
+
+    def health_check(self) -> dict[str, str]:
+        return {
+            "status": "not_loaded",
+            "message": "Local model will be added in Phase 2",
+        }
+
+    def generate(
+        self,
+        messages: list[dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: int = 300,
+    ) -> str:
+        _ = (messages, temperature, max_tokens)
+        return (
+            "[Phase 1 placeholder] The local text model is not loaded yet. "
+            "Mock battle responses are served by the API layer."
+        )

core/minicpm_client.py

@@ -0,0 +1,13 @@
+"""Stub MiniCPM client — OpenBMB integration planned for Phase 9."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def health_check() -> dict[str, Any]:
+    return {
+        "status": "not_configured",
+        "provider": "openbmb",
+        "message": "MiniCPM integration planned for Phase 9",
+    }

core/model_router.py

@@ -0,0 +1,373 @@
+"""Central model routing layer for PitchFight AI.
+
+Routes task requests to the correct model client based on model_mode.
+All model calls are backend-only. Frontend never calls this layer directly.
+
+Supported mode keys:
+  premium_nvidia   — NVIDIA Nemotron 3 Nano Omni 30B-A3B (default)
+  openbmb_omni     — MiniCPM-o 4.5 (Phase 9)
+  tiny_minicpm     — MiniCPM5-1B (Phase 9)
+  vision_deck      — MiniCPM-V 4.6 (Phase 10)
+  whisper_fallback — faster-whisper transcription (Phase 7)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from dotenv import load_dotenv
+
+from core import nvidia_client
+from core import minicpm_client
+from core import vision_client
+from core import transcription_client
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+SUPPORTED_MODES = {
+    "premium_nvidia",
+    "openbmb_omni",
+    "tiny_minicpm",
+    "vision_deck",
+    "whisper_fallback",
+}
+
+_FALLBACK_OPPONENT_MESSAGE = (
+    "Your answer lacked specificity. "
+    "What concrete proof — a metric, a test result, or a user quote — "
+    "can you give me right now to back that claim?"
+)
+
+_FALLBACK_SCORECARD: dict[str, Any] = {
+    "overall": 0,
+    "scores": {},
+    "best_answer": "Model scoring unavailable.",
+    "weakest_answer": "",
+    "improved_answer": "",
+    "improved_pitch": "",
+    "top_3_questions": [],
+    "_fallback": True,
+}
+
+
+def get_default_model_mode() -> str:
+    """Return the configured default model mode."""
+    mode = os.getenv("DEFAULT_MODEL_MODE", "premium_nvidia").strip()
+    return mode if mode in SUPPORTED_MODES else "premium_nvidia"
+
+
+def get_model_health() -> dict[str, Any]:
+    """Return health status for all model clients (no keys exposed)."""
+    return {
+        "default_mode": get_default_model_mode(),
+        "supported_modes": sorted(SUPPORTED_MODES),
+        "providers": {
+            "nvidia": nvidia_client.health_check(),
+            "minicpm": minicpm_client.health_check(),
+            "vision": vision_client.health_check(),
+            "transcription": transcription_client.health_check(),
+        },
+    }
+
+
+def _resolve_mode(model_mode: str | None) -> str:
+    """Validate and return a mode key, falling back to default if invalid."""
+    if model_mode and model_mode in SUPPORTED_MODES:
+        return model_mode
+    default = get_default_model_mode()
+    if model_mode and model_mode not in SUPPORTED_MODES:
+        logger.warning(
+            "Unknown model_mode '%s', falling back to '%s'", model_mode, default
+        )
+    return default
+
+
+def generate_opponent_response(
+    messages: list[dict[str, str]],
+    model_mode: str | None = None,
+    persona: str | None = None,
+    attack_tag: str | None = None,
+) -> dict[str, Any]:
+    """Route an opponent-turn request to the correct model client.
+
+    Returns a result dict:
+      ok       — bool, True on success
+      model_mode — the mode key used
+      provider — which provider was called
+      content  — the model's text response
+      error    — None on success, error description on failure
+    """
+    mode = _resolve_mode(model_mode)
+
+    if mode == "premium_nvidia":
+        return _call_nvidia_opponent(messages, mode)
+
+    if mode in ("openbmb_omni", "tiny_minicpm"):
+        return _placeholder_result(
+            mode,
+            "openbmb",
+            f"OpenBMB mode '{mode}' is planned for Phase 9.",
+        )
+
+    if mode == "vision_deck":
+        return _placeholder_result(
+            mode,
+            "openbmb",
+            "Vision/deck mode is planned for Phase 10.",
+        )
+
+    if mode == "whisper_fallback":
+        return _placeholder_result(
+            mode,
+            "local",
+            "Whisper fallback is planned for Phase 7.",
+        )
+
+    return _placeholder_result(mode, "unknown", f"Unsupported mode: {mode}")
+
+
+def generate_scorecard_response(
+    messages: list[dict[str, str]],
+    model_mode: str | None = None,
+) -> dict[str, Any]:
+    """Route a scorecard-generation request to the correct model client."""
+    mode = _resolve_mode(model_mode)
+
+    if mode == "premium_nvidia":
+        return _call_nvidia_scorecard(messages, mode)
+
+    return _placeholder_result(
+        mode,
+        "mock",
+        f"Scorecard via '{mode}' is not yet implemented. Using mock scorecard.",
+    )
+
+
+def generate_coaching_response(
+    messages: list[dict[str, str]],
+    model_mode: str | None = None,
+) -> dict[str, Any]:
+    """Route a coaching-JSON request to Nemotron (mode=scorecard_coaching).
+
+    Nemotron generates only: improved_answer, improved_pitch, top_3_questions.
+    Thinking is OFF for this mode — direct JSON output is faster and more reliable.
+    """
+    mode = _resolve_mode(model_mode)
+
+    if mode == "premium_nvidia":
+        try:
+            content = nvidia_client.generate_nemotron_response(
+                messages, mode="scorecard_coaching"
+            )
+            return {
+                "ok": True,
+                "model_mode": mode,
+                "provider": "nvidia",
+                "content": content,
+                "error": None,
+            }
+        except RuntimeError as exc:
+            logger.warning("NVIDIA coaching call failed: %s", exc)
+            return {
+                "ok": False,
+                "model_mode": mode,
+                "provider": "nvidia",
+                "content": "",
+                "error": str(exc),
+            }
+
+    return _placeholder_result(mode, "mock", f"Coaching via '{mode}' not implemented.")
+
+
+def generate_coaching_repair_response(
+    raw_bad_content: str,
+    model_mode: str | None = None,
+) -> dict[str, Any]:
+    """Repair a non-JSON coaching response into valid JSON (mode=scorecard_coaching_repair)."""
+    mode = _resolve_mode(model_mode)
+
+    if mode != "premium_nvidia":
+        return _placeholder_result(mode, "mock", "Coaching repair only available for premium_nvidia.")
+
+    repair_messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are a JSON formatter. Convert the input text into the exact JSON schema below. "
+                "Return ONLY valid JSON. First character must be { and last must be }. "
+                "No markdown. No explanation. No preface.\n\n"
+                "REQUIRED SCHEMA:\n"
+                '{"improved_answer": "", "improved_pitch": "", "top_3_questions": ["", "", ""]}'
+            ),
+        },
+        {
+            "role": "user",
+            "content": (
+                "Convert this text into the JSON schema. Output JSON only:\n\n"
+                + raw_bad_content[:4000]
+            ),
+        },
+    ]
+
+    try:
+        content = nvidia_client.generate_nemotron_response(
+            repair_messages, mode="scorecard_coaching_repair"
+        )
+        return {
+            "ok": True,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": content,
+            "error": None,
+        }
+    except RuntimeError as exc:
+        logger.warning("NVIDIA coaching repair call failed: %s", exc)
+        return {
+            "ok": False,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": "",
+            "error": str(exc),
+        }
+
+
+def generate_scorecard_repair_response(
+    raw_bad_content: str,
+    model_mode: str | None = None,
+) -> dict[str, Any]:
+    """Ask Nemotron to repair a non-JSON scorecard response into valid JSON.
+
+    Called when the primary scorecard call returns content that cannot be parsed.
+    Uses temperature=0.0 and mode='scorecard_repair' for a deterministic rewrite.
+
+    Voice mode note:
+        Input is model text output — no source-specific changes needed.
+    """
+    mode = _resolve_mode(model_mode)
+
+    if mode != "premium_nvidia":
+        return _placeholder_result(mode, "mock", "Repair only available for premium_nvidia.")
+
+    repair_messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are a JSON formatter. "
+                "Convert the input text into the exact JSON schema shown below. "
+                "Return ONLY valid JSON. The first character must be { and the last must be }. "
+                "No markdown. No explanation. No preface. No chain-of-thought. "
+                "Fill every field. Use 0 for missing scores. Use empty string for missing text.\n\n"
+                "REQUIRED SCHEMA:\n"
+                '{\n'
+                '  "overall": 0,\n'
+                '  "scores": {\n'
+                '    "clarity":               {"score": 0, "reason": "", "quote": "", "signals_used": []},\n'
+                '    "problem_understanding": {"score": 0, "reason": "", "quote": "", "signals_used": []},\n'
+                '    "market_awareness":      {"score": 0, "reason": "", "quote": "", "signals_used": []},\n'
+                '    "differentiation":       {"score": 0, "reason": "", "quote": "", "signals_used": []},\n'
+                '    "business_model":        {"score": 0, "reason": "", "quote": "", "signals_used": []},\n'
+                '    "objection_handling":    {"score": 0, "reason": "", "quote": "", "signals_used": []}\n'
+                '  },\n'
+                '  "best_answer": "",\n'
+                '  "weakest_answer": "",\n'
+                '  "why_weak": "",\n'
+                '  "improved_answer": "",\n'
+                '  "improved_pitch": "",\n'
+                '  "top_3_questions": ["", "", ""]\n'
+                "}"
+            ),
+        },
+        {
+            "role": "user",
+            "content": (
+                "Convert this text into the JSON schema. "
+                "Extract scores and reasoning from the text below. "
+                "Output JSON only:\n\n"
+                + raw_bad_content[:6000]
+            ),
+        },
+    ]
+
+    try:
+        content = nvidia_client.generate_nemotron_response(
+            repair_messages,
+            mode="scorecard_repair",
+        )
+        return {
+            "ok": True,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": content,
+            "error": None,
+        }
+    except RuntimeError as exc:
+        logger.warning("NVIDIA scorecard repair call failed: %s", exc)
+        return {
+            "ok": False,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": "",
+            "error": str(exc),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _call_nvidia_opponent(messages: list[dict], mode: str) -> dict[str, Any]:
+    try:
+        content = nvidia_client.generate_nemotron_response(messages, mode="opponent")
+        return {
+            "ok": True,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": content,
+            "error": None,
+        }
+    except RuntimeError as exc:
+        logger.warning("NVIDIA opponent call failed: %s", exc)
+        return {
+            "ok": False,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": _FALLBACK_OPPONENT_MESSAGE,
+            "error": str(exc),
+        }
+
+
+def _call_nvidia_scorecard(messages: list[dict], mode: str) -> dict[str, Any]:
+    try:
+        content = nvidia_client.generate_nemotron_response(messages, mode="scorecard")
+        return {
+            "ok": True,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": content,
+            "error": None,
+        }
+    except RuntimeError as exc:
+        logger.warning("NVIDIA scorecard call failed: %s", exc)
+        return {
+            "ok": False,
+            "model_mode": mode,
+            "provider": "nvidia",
+            "content": "",
+            "error": str(exc),
+            "fallback_scorecard": _FALLBACK_SCORECARD,
+        }
+
+
+def _placeholder_result(mode: str, provider: str, message: str) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "model_mode": mode,
+        "provider": provider,
+        "content": _FALLBACK_OPPONENT_MESSAGE,
+        "error": message,
+    }

core/nvidia_client.py

@@ -0,0 +1,234 @@
+"""Backend-only NVIDIA Nemotron API client.
+
+All calls are backend-only. API key is never passed to the frontend.
+Key is read from NVIDIA_API_KEY environment variable only.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from dotenv import load_dotenv
+from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_BASE_URL = "https://integrate.api.nvidia.com/v1"
+_DEFAULT_MODEL = "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning"
+
+# Per-mode settings for nemotron-3-nano-omni-30b-a3b-reasoning.
+#
+# enable_thinking: True  → reasoning model uses internal chain-of-thought
+#                  False → thinking disabled; output is direct (faster, cheaper)
+# reasoning_budget: token budget for internal reasoning (clamped to max_tokens)
+#
+# Modes in main path:
+#   opponent                  — live judge questions during battle (thinking on)
+#   scorecard_coaching        — coaching JSON only (thinking off — faster, more reliable JSON)
+#   scorecard_coaching_repair — JSON repair for coaching output (thinking off)
+#   rewrite                   — rewrite utility (thinking on, lighter budget)
+#   legacy_full_scorecard     — diagnostic / legacy path only; not main path (thinking off)
+_TASK_DEFAULTS: dict[str, dict[str, Any]] = {
+    "opponent": {
+        "enable_thinking": True,
+        "reasoning_budget": 512,
+        "max_tokens": 900,
+        "temperature": 0.65,
+        "top_p": 0.95,
+    },
+    "scorecard_coaching": {
+        "enable_thinking": False,
+        "reasoning_budget": 0,
+        "max_tokens": 1600,
+        "temperature": 0.2,
+        "top_p": 0.95,
+    },
+    "scorecard_coaching_repair": {
+        "enable_thinking": False,
+        "reasoning_budget": 0,
+        "max_tokens": 1200,
+        "temperature": 0.0,
+        "top_p": 0.95,
+    },
+    "rewrite": {
+        "enable_thinking": True,
+        "reasoning_budget": 256,
+        "max_tokens": 900,
+        "temperature": 0.45,
+        "top_p": 0.95,
+    },
+    "legacy_full_scorecard": {
+        "enable_thinking": False,
+        "reasoning_budget": 0,
+        "max_tokens": 3000,
+        "temperature": 0.1,
+        "top_p": 0.95,
+    },
+}
+
+# Modes where the response must be JSON — apply safe extraction from reasoning_content if needed
+_JSON_MODES: frozenset[str] = frozenset({
+    "scorecard_coaching",
+    "scorecard_coaching_repair",
+    "legacy_full_scorecard",
+})
+
+
+def _extract_json_from_reasoning(reasoning: str) -> str | None:
+    """Extract first complete JSON object block from reasoning_content."""
+    start = reasoning.find("{")
+    end = reasoning.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        return reasoning[start : end + 1].strip()
+    return None
+
+
+def _get_config() -> tuple[str, str, str]:
+    """Return (api_key, base_url, model). Raises RuntimeError if key is absent."""
+    api_key = os.getenv("NVIDIA_API_KEY", "").strip()
+    if not api_key:
+        raise RuntimeError(
+            "NVIDIA_API_KEY is not set. "
+            "Add it to your .env file locally or as a HF Space Secret in deployment. "
+            "Never hardcode the key."
+        )
+    base_url = os.getenv("NVIDIA_BASE_URL", _DEFAULT_BASE_URL).strip() or _DEFAULT_BASE_URL
+    model = os.getenv("NVIDIA_OMNI_MODEL", _DEFAULT_MODEL).strip() or _DEFAULT_MODEL
+    return api_key, base_url, model
+
+
+def is_configured() -> bool:
+    """Return True if NVIDIA_API_KEY is present in the environment."""
+    return bool(os.getenv("NVIDIA_API_KEY", "").strip())
+
+
+def health_check() -> dict[str, Any]:
+    """Return configuration status without exposing the API key."""
+    configured = is_configured()
+    base_url = os.getenv("NVIDIA_BASE_URL", _DEFAULT_BASE_URL)
+    model = os.getenv("NVIDIA_OMNI_MODEL", _DEFAULT_MODEL)
+    return {
+        "provider": "nvidia",
+        "configured": configured,
+        "base_url": base_url,
+        "model": model,
+        "api_key_present": configured,
+        "message": (
+            "NVIDIA client ready" if configured
+            else "NVIDIA_API_KEY missing — add to .env or HF Space Secrets"
+        ),
+    }
+
+
+def generate_nemotron_response(
+    messages: list[dict[str, str]],
+    mode: str = "opponent",
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    timeout: int = 30,
+) -> str:
+    """Call NVIDIA Nemotron and return the response text.
+
+    Args:
+        messages: OpenAI-format message list [{"role": ..., "content": ...}, ...]
+        mode: task type key — "opponent", "scorecard_coaching", "rewrite", etc.
+        temperature: overrides mode default if provided
+        max_tokens: overrides mode default if provided
+        timeout: request timeout in seconds
+
+    Returns:
+        Response text string from the model.
+
+    Raises:
+        RuntimeError: on missing key or any API failure (clean message, no key leak).
+    """
+    api_key, base_url, model = _get_config()
+
+    defaults = _TASK_DEFAULTS.get(mode, _TASK_DEFAULTS["opponent"])
+    temp = temperature if temperature is not None else defaults["temperature"]
+    tokens = max_tokens if max_tokens is not None else defaults["max_tokens"]
+    top_p: float = defaults.get("top_p", 0.95)
+    enable_thinking: bool = defaults.get("enable_thinking", True)
+    # reasoning_budget must not exceed max_tokens
+    reasoning_budget: int = min(defaults.get("reasoning_budget", 0), tokens)
+
+    client = OpenAI(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+    )
+
+    try:
+        completion = client.chat.completions.create(
+            model=model,
+            messages=messages,  # type: ignore[arg-type]
+            temperature=temp,
+            max_tokens=tokens,
+            top_p=top_p,
+            extra_body={
+                "chat_template_kwargs": {"enable_thinking": enable_thinking},
+                "reasoning_budget": reasoning_budget,
+            },
+        )
+        msg = completion.choices[0].message
+        content = (msg.content or "").strip()
+        reasoning = (getattr(msg, "reasoning_content", None) or "").strip()
+
+        if not content:
+            if mode in _JSON_MODES and reasoning:
+                # For JSON modes: try to salvage a JSON block from reasoning_content
+                extracted = _extract_json_from_reasoning(reasoning)
+                if extracted:
+                    logger.info(
+                        "Nemotron content empty; extracted JSON block from reasoning_content (mode=%s)",
+                        mode,
+                    )
+                    content = extracted
+                else:
+                    logger.warning(
+                        "Nemotron content empty; checked reasoning_content fallback (mode=%s, no JSON found)",
+                        mode,
+                    )
+            elif reasoning:
+                # Non-JSON mode (e.g. opponent): use reasoning trace as last resort
+                logger.warning(
+                    "Nemotron content empty; checked reasoning_content fallback (mode=%s)",
+                    mode,
+                )
+                content = reasoning
+
+        if not content:
+            raise RuntimeError(
+                "NVIDIA model returned an empty response. "
+                "The reasoning model may need a larger max_tokens budget."
+            )
+
+        return content
+
+    except APITimeoutError:
+        logger.warning("NVIDIA API timed out after %ds (mode=%s)", timeout, mode)
+        raise RuntimeError(
+            f"NVIDIA Nemotron request timed out after {timeout}s. "
+            "Check your connection or increase timeout."
+        )
+    except APIConnectionError as exc:
+        logger.warning("NVIDIA API connection error: %s", exc)
+        raise RuntimeError(
+            "Could not connect to NVIDIA API. "
+            "Verify NVIDIA_BASE_URL and your network connection."
+        )
+    except APIStatusError as exc:
+        logger.warning("NVIDIA API status error %s: %s", exc.status_code, exc.message)
+        raise RuntimeError(
+            f"NVIDIA API returned HTTP {exc.status_code}. "
+            "Check your NVIDIA_API_KEY and model ID."
+        )
+    except Exception as exc:
+        logger.warning("NVIDIA API unexpected error: %s", type(exc).__name__)
+        raise RuntimeError(
+            f"NVIDIA model call failed ({type(exc).__name__}). See server logs."
+        )

core/output_sanitizer.py

@@ -0,0 +1,63 @@
+"""Sanitizer for Nemotron judge output to remove instruction leakage."""
+
+from __future__ import annotations
+
+import re
+
+_LEAKAGE_PATTERNS = [
+    r"we need to\b",
+    r"the prompt says\b",
+    r"the instruction says\b",
+    r"as instructed\b",
+    r"my instructions\b",
+    r"according to my system prompt\b",
+    r"i am supposed to\b",
+    r"i should follow\b",
+    r"the rules say\b",
+    r"let'?s parse\b",
+    r"^first[,\s]",
+    r"\bneed to\b.*\binstructions?\b",
+    r"we have to note\b",
+    r"i should\b.*\binstructions?\b",
+    r"per the instructions?\b",
+    r"based on the instructions?\b",
+]
+
+_LEAKAGE_RE = re.compile(
+    "|".join(_LEAKAGE_PATTERNS),
+    re.IGNORECASE,
+)
+
+_SAFE_FALLBACK = (
+    "What concrete evidence can you give me right now to back that claim?"
+)
+
+
+def sanitize_model_output(text: str) -> str:
+    """Remove instruction-leakage lines from Nemotron judge output.
+
+    Splits by sentence/line, drops any that contain leakage patterns,
+    returns the joined remainder. If nothing survives, returns a safe
+    fallback question.
+    """
+    if not text:
+        return _SAFE_FALLBACK
+
+    # Split on newlines first, then also on sentence boundaries
+    lines = text.splitlines()
+    clean_lines: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if _LEAKAGE_RE.search(stripped):
+            continue
+        clean_lines.append(stripped)
+
+    result = " ".join(clean_lines).strip()
+
+    # If too little survived, return fallback
+    if len(result.split()) < 4:
+        return _SAFE_FALLBACK
+
+    return result

core/persona_builder.py

@@ -0,0 +1,66 @@
+"""Persona prompt builder for AI opponents."""
+
+from __future__ import annotations
+
+PERSONA_LABELS = {
+    "skeptical_vc": "Skeptical VC",
+    "technical_judge": "Technical Judge",
+    "hackathon_judge": "Hackathon Judge",
+}
+
+
+def build_persona_prompt(
+    persona: str,
+    startup: dict,
+    difficulty: str = "high",
+) -> str:
+    """Build a system prompt for the selected opponent persona."""
+    label = PERSONA_LABELS.get(persona, "Tough Judge")
+    name = startup.get("name", "this startup")
+    problem = startup.get("problem", "")
+    solution = startup.get("solution", "")
+    why_ai = startup.get("why_ai", "")
+
+    rules = """
+Behavior rules:
+- Ask one sharp question at a time.
+- Keep responses under 4 sentences.
+- Reference the founder's previous answer when pushing back.
+- Do not give advice during the battle.
+- Do not compliment the founder.
+- Attack vague, generic, or unsubstantiated claims.
+- Raise difficulty after strong answers.
+- Stay in character at all times.
+- Be firm but not abusive.
+""".strip()
+
+    persona_focus = {
+        "skeptical_vc": (
+            "You are a skeptical venture capitalist evaluating whether this is a real business. "
+            "Attack market size, moat, retention, revenue logic, competition, and defensibility."
+        ),
+        "technical_judge": (
+            "You are a senior technical judge who stress-tests whether AI is necessary and whether "
+            "the system can actually work at scale. Attack architecture, data quality, latency, "
+            "and simpler alternatives."
+        ),
+        "hackathon_judge": (
+            "You are a hackathon judge deciding if this project deserves a prize. "
+            "Attack novelty, demo clarity, MVP strength, user pain, and whether AI is load-bearing."
+        ),
+    }
+
+    focus = persona_focus.get(persona, persona_focus["hackathon_judge"])
+
+    return f"""You are {label}, a tough pitch opponent in PitchFight AI.
+Difficulty: {difficulty}
+
+Startup: {name}
+Problem: {problem}
+Solution: {solution}
+Why AI: {why_ai}
+
+{focus}
+
+{rules}
+"""

core/samples.py

@@ -0,0 +1,27 @@
+"""Sample startup data for demos and testing."""
+
+EVENTRADAR_SAMPLE = {
+    "name": "EventRadar AI",
+    "problem": (
+        "Students miss hackathons, tech events, and startup opportunities because "
+        "discovery is scattered across WhatsApp groups, LinkedIn, Luma, college clubs, "
+        "and random websites."
+    ),
+    "target_users": "College students, student founders, and early-stage builders.",
+    "solution": (
+        "AI-powered event discovery that ranks opportunities based on skills, goals, "
+        "location, and deadline urgency."
+    ),
+    "why_ai": (
+        "The app does not just list events. It matches events to a student's profile "
+        "and explains why each event is worth attending."
+    ),
+    "competitors": "Luma, LinkedIn Events, WhatsApp groups, college club pages.",
+    "traction": "Prototype built with scraped event data and ranking logic.",
+    "ask": "Hackathon prize and mentor feedback.",
+}
+
+
+def get_sample_startup() -> dict:
+    """Return the EventRadar AI sample startup."""
+    return dict(EVENTRADAR_SAMPLE)

core/scoring_engine.py

@@ -0,0 +1,908 @@
+"""Scoring engine for PitchFight AI — Phase 5D: Hybrid Claim-Based Scorecard.
+
+Architecture (permanent):
+  - Local deterministic logic scores all 6 dimensions using extracted signals.
+  - Nemotron generates ONLY: improved_answer, improved_pitch, top_3_questions.
+  - No giant fragile Nemotron full-scorecard JSON in the main path.
+
+scorecard_source values:
+  "hybrid_claims_nemotron" — local scores + Nemotron coaching succeeded
+  "hybrid_claims_local"    — local scores + local coaching fallback (still useful)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from core import model_router
+from core.json_utils import safe_json_parse, _score_label
+from core.claim_extractor import extract_concrete_signals
+
+logger = logging.getLogger(__name__)
+
+MAX_ROUNDS = int(os.getenv("MAX_ROUNDS", "6"))
+
+_REQUIRED_DIMS = (
+    "clarity",
+    "problem_understanding",
+    "market_awareness",
+    "differentiation",
+    "business_model",
+    "objection_handling",
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _clamp(v: int, lo: int = 0, hi: int = 100) -> int:
+    return max(lo, min(hi, v))
+
+
+def _dimension(score: int, reason: str, quote: str, signals: list[str] | None = None) -> dict:
+    return {
+        "score": score,
+        "label": _score_label(score),
+        "reason": reason,
+        "quote": quote,
+        "signals_used": signals or [],
+    }
+
+
+def _empty_signals() -> dict:
+    return {
+        "numbers": [], "percentages": [], "pricing": [], "user_counts": [],
+        "validation": [], "college_mentions": [], "competitors": [],
+        "technical_mechanisms": [], "revenue_signals": [], "retention_signals": [],
+        "gtm_signals": [], "non_answers": [], "vague_claims": [],
+        "best_user_quotes": [], "all_user_answers": [], "signal_count": 0,
+    }
+
+
+def _first(lst: list, default: str = "") -> str:
+    return lst[0] if lst else default
+
+
+# ---------------------------------------------------------------------------
+# Local dimension scoring functions
+# ---------------------------------------------------------------------------
+
+def _score_clarity(signals: dict, engagement: int, total: int) -> tuple[int, str, str, list]:
+    """Did the founder communicate what the product does and who it helps?"""
+    has_tech = bool(signals.get("technical_mechanisms"))
+    has_numbers = bool(signals.get("numbers") or signals.get("user_counts"))
+    has_validation = bool(signals.get("validation"))
+    has_vague_only = bool(signals.get("vague_claims")) and not has_tech and not has_numbers
+    best_quotes = signals.get("best_user_quotes", [])
+    quote = best_quotes[0][:160] if best_quotes else ""
+    used: list[str] = []
+
+    if engagement == 0:
+        return 15, "No substantive answers — product explanation absent.", quote, []
+
+    # Floor: any on-topic answer = at least 33
+    score = 33
+    parts: list[str] = []
+
+    if has_tech and (has_numbers or has_validation):
+        score = max(score, 65)
+        techs = signals.get("technical_mechanisms", [])[:2]
+        used += techs
+        parts.append(f"Technical mechanism described ({', '.join(techs)}) with supporting evidence.")
+    elif has_tech:
+        score = max(score, 58)
+        techs = signals.get("technical_mechanisms", [])[:2]
+        used += techs
+        parts.append(f"Technical mechanism explained: {', '.join(techs)}.")
+    elif has_validation:
+        score = max(score, 55)
+        vals = signals.get("validation", [])[:2]
+        used += vals
+        parts.append(f"Validation evidence present ({', '.join(vals)}) — product is real.")
+    elif has_numbers:
+        score = max(score, 52)
+        nums = signals.get("numbers", [])[:2]
+        used += nums
+        parts.append(f"Concrete numbers ({', '.join(nums)}) suggest product has been built/used.")
+    elif has_vague_only:
+        score = _clamp(score, 33, 40)
+        parts.append("Answer was on-topic but used vague language without concrete specifics.")
+    else:
+        parts.append("Product described with some substance but limited concrete evidence.")
+
+    reason = " ".join(parts)[:280]
+    return _clamp(score), reason, quote, list(dict.fromkeys(used))[:5]
+
+
+def _score_problem_understanding(signals: dict, engagement: int, total: int) -> tuple[int, str, str, list]:
+    """Did they name a specific user, pain, and provide evidence of understanding?"""
+    has_validation = bool(signals.get("validation"))
+    has_colleges = bool(signals.get("college_mentions"))
+    has_user_counts = bool(signals.get("user_counts") or signals.get("numbers"))
+    val_list = signals.get("validation", [])
+    col_list = signals.get("college_mentions", [])
+    num_list = (signals.get("user_counts", []) + signals.get("numbers", []))[:2]
+    best_quotes = signals.get("best_user_quotes", [])
+    quote = (val_list[0] if val_list else (col_list[0] if col_list else (best_quotes[0][:160] if best_quotes else "")))
+    used: list[str] = (val_list[:2] + col_list[:2])[:5]
+
+    if engagement == 0:
+        return 15, "No evidence of problem understanding — no substantive answers.", quote[:160], []
+
+    score = 33
+    parts: list[str] = []
+
+    if has_validation and has_colleges:
+        score = max(score, 72)
+        parts.append(
+            f"Validated with real users ({', '.join(val_list[:2])}) "
+            f"at named campuses ({', '.join(col_list[:2])})."
+        )
+    elif has_validation:
+        score = max(score, 62)
+        parts.append(f"Validation evidence: {', '.join(val_list[:2])}.")
+    elif has_colleges:
+        score = max(score, 52)
+        parts.append(f"Campus/college context mentioned: {', '.join(col_list[:2])}.")
+    elif has_user_counts:
+        score = max(score, 50)
+        parts.append(f"User/number evidence present: {', '.join(num_list)}.")
+    else:
+        parts.append("Problem described but without user research or validation evidence.")
+
+    return _clamp(score), " ".join(parts)[:280], quote[:160] if isinstance(quote, str) else "", used
+
+
+def _score_market_awareness(signals: dict, engagement: int, total: int) -> tuple[int, str, str, list]:
+    """Did they demonstrate knowledge of market size, segment, or competitive landscape?"""
+    has_numbers = bool(signals.get("numbers") or signals.get("user_counts"))
+    has_competitors = bool(signals.get("competitors"))
+    has_colleges = bool(signals.get("college_mentions"))
+    nums = (signals.get("user_counts", []) + signals.get("numbers", []))[:3]
+    comps = signals.get("competitors", [])[:3]
+    best_quotes = signals.get("best_user_quotes", [])
+    quote = (nums[0] if nums else (comps[0] if comps else (best_quotes[0][:160] if best_quotes else "")))
+    used: list[str] = (nums[:2] + comps[:2])[:5]
+
+    if engagement == 0:
+        return 15, "No market awareness demonstrated — no substantive answers.", str(quote)[:160], []
+
+    score = 33
+    parts: list[str] = []
+
+    if has_numbers and has_competitors:
+        score = max(score, 67)
+        parts.append(
+            f"Market numbers ({', '.join(nums[:2])}) and competitors named ({', '.join(comps[:2])})."
+        )
+    elif has_numbers and has_colleges:
+        score = max(score, 60)
+        parts.append(
+            f"User/market numbers ({', '.join(nums[:2])}) with campus context."
+        )
+    elif has_numbers:
+        score = max(score, 55)
+        parts.append(f"Market/user numbers: {', '.join(nums[:2])}.")
+    elif has_competitors:
+        score = max(score, 48)
+        parts.append(
+            f"Competitors identified ({', '.join(comps[:2])}) — indicates market awareness."
+        )
+    else:
+        parts.append("Market described but without user counts, TAM, or competitor landscape.")
+
+    return _clamp(score), " ".join(parts)[:280], str(quote)[:160], used
+
+
+def _score_differentiation(signals: dict, engagement: int, total: int) -> tuple[int, str, str, list]:
+    """Did they explain why this beats alternatives (competitor + mechanism/moat)?"""
+    has_competitors = bool(signals.get("competitors"))
+    has_tech = bool(signals.get("technical_mechanisms"))
+    comps = signals.get("competitors", [])[:3]
+    techs = signals.get("technical_mechanisms", [])[:3]
+    best_quotes = signals.get("best_user_quotes", [])
+    quote = (comps[0] if comps else (techs[0] if techs else (best_quotes[0][:160] if best_quotes else "")))
+    used: list[str] = (comps[:2] + techs[:2])[:5]
+
+    if engagement == 0:
+        return 15, "No differentiation demonstrated — no substantive answers.", str(quote)[:160], []
+
+    score = 33
+    parts: list[str] = []
+
+    if has_competitors and has_tech:
+        score = max(score, 70)
+        parts.append(
+            f"Named competitors ({', '.join(comps[:2])}) with technical moat ({', '.join(techs[:2])})."
+        )
+    elif has_competitors:
+        score = max(score, 52)
+        parts.append(
+            f"Competitors identified ({', '.join(comps[:2])}) but moat/mechanism not fully articulated."
+        )
+    elif has_tech:
+        score = max(score, 50)
+        parts.append(
+            f"Technical approach described ({', '.join(techs[:2])}) but no direct competitor comparison."
+        )
+    else:
+        parts.append(
+            "Differentiation not clearly supported — no competitors named and no technical mechanism stated."
+        )
+
+    return _clamp(score), " ".join(parts)[:280], str(quote)[:160], used
+
+
+def _score_business_model(signals: dict, engagement: int, total: int) -> tuple[int, str, str, list]:
+    """Did they explain who pays, how much, and why?"""
+    has_pricing = bool(signals.get("pricing"))
+    has_revenue = bool(signals.get("revenue_signals"))
+    has_validation = bool(signals.get("validation"))
+    pricing = signals.get("pricing", [])[:3]
+    revenue = signals.get("revenue_signals", [])[:3]
+    best_quotes = signals.get("best_user_quotes", [])
+    quote = (pricing[0] if pricing else (revenue[0] if revenue else (best_quotes[0][:160] if best_quotes else "")))
+    used: list[str] = (pricing[:2] + revenue[:2])[:5]
+
+    if engagement == 0:
+        return 12, "No business model addressed — all non-answers.", str(quote)[:160], []
+
+    # Business model floor is lower — it's OK for early-stage students to not have revenue
+    score = 28
+    parts: list[str] = []
+
+    if has_pricing and has_revenue:
+        score = max(score, 68)
+        parts.append(f"Pricing ({', '.join(pricing[:2])}) and revenue logic ({', '.join(revenue[:2])}) present.")
+    elif has_pricing:
+        score = max(score, 52)
+        parts.append(f"Pricing mentioned: {', '.join(pricing[:2])}.")
+    elif has_revenue:
+        score = max(score, 48)
+        parts.append(f"Revenue/monetization signals: {', '.join(revenue[:2])}.")
+    elif has_validation:
+        # Traction is a proxy for business activity, even if no explicit model yet
+        score = max(score, 36)
+        parts.append(
+            "Traction/validation evidence present but no explicit pricing or revenue model stated."
+        )
+    else:
+        parts.append("Business model not clearly stated — no pricing, revenue, or monetization mentioned.")
+
+    return _clamp(score), " ".join(parts)[:280], str(quote)[:160], used
+
+
+def _score_objection_handling(signals: dict, engagement: int, total: int) -> tuple[int, str, str, list]:
+    """Did they answer hard questions directly with evidence?"""
+    has_validation = bool(signals.get("validation"))
+    has_numbers = bool(signals.get("numbers") or signals.get("user_counts"))
+    has_tech = bool(signals.get("technical_mechanisms"))
+    best_quotes = signals.get("best_user_quotes", [])
+    quote = best_quotes[0][:160] if best_quotes else ""
+    used: list[str] = (signals.get("validation", [])[:2] + signals.get("numbers", [])[:2])[:4]
+
+    if total == 0 or engagement == 0:
+        return 15, "No substantive answers to objections recorded.", quote, []
+
+    engagement_rate = engagement / total
+    # Base score: engagement_rate * 60
+    score = int(engagement_rate * 60)
+    parts: list[str] = []
+
+    if has_validation:
+        score += 10
+        vals = signals.get("validation", [])[:2]
+        parts.append(f"Evidence-backed answers: {', '.join(vals)}.")
+    if has_numbers:
+        score += 7
+        parts.append("Concrete numbers used to support claims.")
+    if has_tech:
+        score += 5
+
+    # Floor: at least 30 if majority were substantive
+    if engagement_rate > 0.5:
+        score = max(score, 30)
+
+    if not parts:
+        parts.append(
+            f"{engagement}/{total} answers were substantive. Limited evidence-backed responses to objections."
+        )
+    else:
+        parts.insert(0, f"{engagement}/{total} answers substantive.")
+
+    return _clamp(score, 0, 82), " ".join(parts)[:280], quote, used
+
+
+# ---------------------------------------------------------------------------
+# Local scoring orchestrator
+# ---------------------------------------------------------------------------
+
+def _why_weak_reason(weak_answer: str, signals: dict) -> str:
+    stripped = weak_answer.strip().lower()
+    if not stripped or stripped in ("no answers recorded.", "no answers recorded yet."):
+        return "No answers were recorded in this session."
+    if len(stripped.split()) < 4:
+        return "This answer was too brief to evaluate — no supporting evidence given."
+    if signals.get("vague_claims") and not signals.get("numbers") and not signals.get("validation"):
+        return "This answer used vague language without concrete evidence or specifics."
+    return "This answer lacked the concrete numbers, validation, or mechanisms present in stronger answers."
+
+
+def _compute_local_scores(
+    signals: dict, startup: dict
+) -> tuple[dict[str, Any], str, str, str]:
+    """Return (scores_dict, best_answer, weakest_answer, why_weak).
+
+    All 6 dimension scores are computed deterministically from extracted signals.
+    No API calls.
+    """
+    all_answers = signals.get("all_user_answers", [])
+    non_answers = signals.get("non_answers", [])
+    best_quotes = signals.get("best_user_quotes", [])
+    total = len(all_answers)
+    engagement = total - len(non_answers)  # number of substantive answers
+
+    scores = {
+        "clarity": _dimension(
+            *_score_clarity(signals, engagement, total)
+        ),
+        "problem_understanding": _dimension(
+            *_score_problem_understanding(signals, engagement, total)
+        ),
+        "market_awareness": _dimension(
+            *_score_market_awareness(signals, engagement, total)
+        ),
+        "differentiation": _dimension(
+            *_score_differentiation(signals, engagement, total)
+        ),
+        "business_model": _dimension(
+            *_score_business_model(signals, engagement, total)
+        ),
+        "objection_handling": _dimension(
+            *_score_objection_handling(signals, engagement, total)
+        ),
+    }
+
+    best_answer = (
+        best_quotes[0]
+        if best_quotes
+        else (all_answers[0] if all_answers else "No answers recorded.")
+    )
+    non_best = [a for a in all_answers if a != best_answer]
+    if non_answers:
+        weakest_answer = non_answers[0]
+    elif non_best:
+        weakest_answer = min(non_best, key=len)
+    else:
+        weakest_answer = all_answers[-1] if len(all_answers) > 1 else best_answer
+
+    why_weak = _why_weak_reason(weakest_answer, signals)
+    return scores, best_answer, weakest_answer, why_weak
+
+
+# ---------------------------------------------------------------------------
+# Coaching prompt builder (Nemotron generates only 3 coaching fields)
+# ---------------------------------------------------------------------------
+
+def _build_coaching_prompt(
+    session: dict,
+    signals: dict,
+    scores: dict[str, Any],
+    best_answer: str,
+    weakest_answer: str,
+    why_weak: str,
+) -> list[dict[str, str]]:
+    """Build messages for Nemotron coaching-only call.
+
+    Nemotron generates only: improved_answer, improved_pitch, top_3_questions.
+    All scoring is already done locally and passed as context.
+    """
+    startup = session.get("startup", {})
+
+    startup_block = "\n".join([
+        f"Startup: {startup.get('name', 'Unknown')}",
+        f"Problem: {startup.get('problem', 'Not stated')}",
+        f"Solution: {startup.get('solution', 'Not stated')}",
+        f"Why AI: {startup.get('why_ai', 'Not stated')}",
+        f"Stage: {startup.get('stage', 'Not stated')}",
+        f"Traction: {startup.get('traction', 'Not stated')}",
+        f"Target users: {startup.get('target_users', 'Not stated')}",
+    ])
+
+    # Scores block + weak dimensions (explicit requirement)
+    scores_lines = ["DIMENSION SCORES (local — do not re-score):"]
+    weak_dims: list[tuple[str, int, str]] = []
+    for dim in _REQUIRED_DIMS:
+        d = scores.get(dim, {})
+        s = d.get("score", 0)
+        lbl = d.get("label", "")
+        reason_snippet = d.get("reason", "")[:80]
+        scores_lines.append(f"  {dim}: {s} ({lbl})")
+        if s < 55:
+            weak_dims.append((dim, s, lbl, reason_snippet))
+
+    scores_block = "\n".join(scores_lines)
+
+    if weak_dims:
+        weak_lines = ["\nWEAK DIMENSIONS (score < 55) — focus improved_answer and top_3_questions here:"]
+        for dim, s, lbl, reason_snippet in weak_dims:
+            weak_lines.append(f"  {dim}: {s} ({lbl}) — {reason_snippet}")
+        weak_block = "\n".join(weak_lines)
+    else:
+        weak_block = "\nAll dimensions Solid or above — focus coaching on deepening evidence."
+
+    # Signals block
+    sig_lines = ["CONCRETE SIGNALS EXTRACTED FROM ANSWERS:"]
+    for key, label in [
+        ("numbers", "Numbers/metrics"),
+        ("validation", "Validation evidence"),
+        ("competitors", "Competitors"),
+        ("pricing", "Pricing/currency"),
+        ("technical_mechanisms", "Technical mechanisms"),
+        ("college_mentions", "Colleges/campuses"),
+    ]:
+        items = signals.get(key, [])[:4]
+        if items:
+            sig_lines.append(f"  {label}: {', '.join(str(x) for x in items)}")
+    signals_block = "\n".join(sig_lines)
+
+    # Actual answers block
+    all_answers = signals.get("all_user_answers", [])
+    answers_lines = ["ACTUAL FOUNDER ANSWERS (use these — do not hallucinate):"]
+    for i, a in enumerate(all_answers[:5], 1):
+        answers_lines.append(f"  {i}. {a[:200]}")
+    answers_block = "\n".join(answers_lines)
+
+    system_content = (
+        "Return ONLY valid JSON. First character must be {. Last character must be }.\n"
+        "No markdown. No explanation. No analysis. No reasoning. No chain-of-thought.\n\n"
+        "You are a startup pitch coach for a student founder. "
+        "Generate coaching content based on the provided context.\n\n"
+        "RULES:\n"
+        "  - Do NOT hallucinate traction, numbers, or facts not in the provided context.\n"
+        "  - Do NOT re-score — scores are already computed.\n"
+        "  - Use actual startup context and actual founder answers.\n"
+        "  - If concrete signals exist, reference them in improved_answer and improved_pitch.\n"
+        "  - improved_answer: rewrite of the weakest answer using specifics the founder already knows.\n"
+        "  - improved_pitch: one concise 60-second pitch using startup name, problem, solution, evidence.\n"
+        "  - top_3_questions: 3 pointed follow-up questions an investor would ask, focused on weak dimensions.\n\n"
+        "Return exactly this JSON schema — nothing else:\n"
+        '{"improved_answer": "string", "improved_pitch": "string", "top_3_questions": ["string", "string", "string"]}'
+    )
+
+    user_content = (
+        f"STARTUP CONTEXT:\n{startup_block}\n\n"
+        f"{scores_block}\n"
+        f"{weak_block}\n\n"
+        f"{signals_block}\n\n"
+        f"BEST ANSWER (strongest): {best_answer[:300]}\n\n"
+        f"WEAKEST ANSWER: {weakest_answer[:200]}\n"
+        f"WHY WEAK: {why_weak}\n\n"
+        f"{answers_block}\n\n"
+        "Generate improved_answer, improved_pitch, and top_3_questions. Return JSON only."
+    )
+
+    return [
+        {"role": "system", "content": system_content},
+        {"role": "user", "content": user_content},
+    ]
+
+
+def _parse_coaching_json(raw: str) -> dict[str, Any] | None:
+    """Parse and validate the coaching JSON response."""
+    parsed = safe_json_parse(raw)
+    if not parsed or not isinstance(parsed, dict):
+        return None
+
+    improved_answer = str(parsed.get("improved_answer", "")).strip()
+    improved_pitch = str(parsed.get("improved_pitch", "")).strip()
+    raw_q = parsed.get("top_3_questions", [])
+
+    if isinstance(raw_q, list):
+        questions = [str(q).strip() for q in raw_q if str(q).strip()][:3]
+    else:
+        questions = []
+
+    while len(questions) < 3:
+        questions.append("What concrete evidence can you give to support your strongest claim?")
+
+    # Both coaching fields must be non-empty for the parse to be considered valid
+    if not improved_answer or not improved_pitch:
+        return None
+
+    return {
+        "improved_answer": improved_answer,
+        "improved_pitch": improved_pitch,
+        "top_3_questions": questions,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Local coaching fallback helpers
+# ---------------------------------------------------------------------------
+
+def _local_improved_answer(weak: str, startup: dict, signals: dict) -> str:
+    name = startup.get("name", "our product")
+    parts: list[str] = [f"A stronger version would anchor in specifics. {name} "]
+    numbers = signals.get("numbers", []) + signals.get("user_counts", [])
+    validation = signals.get("validation", [])
+    competitors = signals.get("competitors", [])
+    if numbers:
+        parts.append(f"has demonstrated by {', '.join(numbers[:3])} ")
+    if validation:
+        parts.append(f"validated through {', '.join(validation[:2])} ")
+    if competitors:
+        parts.append(f"and is differentiated from {', '.join(competitors[:2])} ")
+    parts.append(f'(Original answer was: "{weak[:100]}")')
+    return "".join(parts)
+
+
+def _local_improved_pitch(startup: dict, signals: dict) -> str:
+    name = startup.get("name", "Our startup")
+    problem = startup.get("problem", "a student pain point")
+    solution = startup.get("solution", "a focused product")
+    evidence = (
+        signals.get("user_counts", []) +
+        signals.get("validation", []) +
+        signals.get("numbers", [])
+    )[:3]
+    pitch = f"{name} solves {problem}. Our solution: {solution}."
+    if evidence:
+        pitch += f" Evidence so far: {', '.join(evidence)}."
+    pricing = signals.get("pricing", [])
+    if pricing:
+        pitch += f" Business model: {pricing[0]}."
+    return pitch
+
+
+def _fallback_questions(weakest_dims: list[tuple], startup: dict) -> list[str]:
+    _q = {
+        "clarity":               "In one sentence, what does your product do and who does it help?",
+        "problem_understanding": "What is the most painful part of this problem for your user, and how do you know?",
+        "market_awareness":      "How many potential users exist in year one, and how did you arrive at that number?",
+        "differentiation":       "What would a student miss if they used a competitor instead of you?",
+        "business_model":        "Who pays, how much, and what triggers the first payment?",
+        "objection_handling":    "What is the strongest argument that this startup will not work, and how do you respond?",
+    }
+    out = [
+        _q.get(dim, f"What evidence do you have for your {dim.replace('_', ' ')}?")
+        for dim, _ in weakest_dims[:3]
+    ]
+    while len(out) < 3:
+        out.append("What concrete evidence can you give to back your strongest claim?")
+    return out[:3]
+
+
+def _local_coaching(
+    weakest: str,
+    startup: dict,
+    signals: dict,
+    scores: dict[str, Any],
+) -> dict[str, Any]:
+    """Generate local coaching content when Nemotron coaching fails."""
+    dim_sorted = sorted(scores.items(), key=lambda x: x[1]["score"])
+    return {
+        "improved_answer": _local_improved_answer(weakest, startup, signals),
+        "improved_pitch": _local_improved_pitch(startup, signals),
+        "top_3_questions": _fallback_questions(dim_sorted, startup),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Main hybrid scorecard generator (Phase 5D — permanent architecture)
+# ---------------------------------------------------------------------------
+
+def generate_claim_based_scorecard(
+    session: dict, model_mode: str | None = None
+) -> dict[str, Any]:
+    """Hybrid claim-based scorecard.
+
+    Local scoring → deterministic, signal-based, always fair to student founders.
+    Nemotron coaching → generates improved_answer, improved_pitch, top_3_questions only.
+
+    Returns a frontend-safe dict with all required fields on every path.
+    """
+    resolved_mode = model_mode or session.get("model_mode") or os.getenv(
+        "DEFAULT_MODEL_MODE", "premium_nvidia"
+    )
+    startup = session.get("startup", {})
+
+    # Step 1: Extract signals (local, no API)
+    try:
+        signals = extract_concrete_signals(session)
+    except Exception as exc:
+        logger.warning("scoring_engine: signal extraction failed: %s", exc)
+        signals = _empty_signals()
+
+    # Step 2: Compute all 6 dimension scores + best/weakest answers locally
+    try:
+        scores, best_answer, weakest_answer, why_weak = _compute_local_scores(signals, startup)
+    except Exception as exc:
+        logger.warning("scoring_engine: local scoring failed: %s", exc)
+        return build_session_aware_fallback_scorecard(
+            session, signals, f"Local scoring error: {type(exc).__name__}"
+        )
+
+    # Step 3: Compute overall and concrete_signals_summary locally
+    overall = round(sum(d["score"] for d in scores.values()) / len(scores))
+    concrete_signals_summary = {
+        "numbers":              signals.get("numbers", [])[:6],
+        "validation":           signals.get("validation", [])[:6],
+        "competitors":          signals.get("competitors", [])[:6],
+        "revenue_signals":      signals.get("revenue_signals", [])[:6],
+        "technical_mechanisms": signals.get("technical_mechanisms", [])[:6],
+    }
+
+    # Step 4: Call Nemotron for coaching only
+    coaching: dict[str, Any] | None = None
+    coaching_error: str = ""
+    coaching_raw: str = ""
+
+    try:
+        coaching_messages = _build_coaching_prompt(
+            session, signals, scores, best_answer, weakest_answer, why_weak
+        )
+        coaching_result = model_router.generate_coaching_response(
+            coaching_messages, model_mode=resolved_mode
+        )
+        if coaching_result.get("ok") and coaching_result.get("content"):
+            coaching_raw = coaching_result["content"]
+            coaching = _parse_coaching_json(coaching_raw)
+            if coaching:
+                logger.info("scoring_engine: Nemotron coaching JSON parsed OK")
+            else:
+                logger.warning("scoring_engine: primary coaching parse failed, raw[:200]=%r", coaching_raw[:200])
+        else:
+            coaching_error = coaching_result.get("error") or "Coaching model returned empty response"
+            logger.warning("scoring_engine: coaching call not ok — %s", coaching_error)
+    except Exception as exc:
+        coaching_error = f"Coaching error: {type(exc).__name__}"
+        logger.warning("scoring_engine: coaching call raised — %s", exc)
+
+    # Step 5: Repair retry if JSON parse failed (content was returned but not valid JSON)
+    if coaching is None and coaching_raw:
+        logger.info("scoring_engine: attempting coaching JSON repair")
+        try:
+            repair_result = model_router.generate_coaching_repair_response(
+                coaching_raw, model_mode=resolved_mode
+            )
+            if repair_result.get("ok") and repair_result.get("content"):
+                coaching = _parse_coaching_json(repair_result["content"])
+                if coaching:
+                    logger.info("scoring_engine: repaired coaching JSON OK")
+                else:
+                    logger.warning("scoring_engine: repair coaching parse also failed")
+        except Exception as exc:
+            logger.warning("scoring_engine: coaching repair raised — %s", exc)
+
+    # Step 6: Local coaching fallback if Nemotron failed
+    if coaching is None:
+        logger.warning(
+            "scoring_engine: using local coaching fallback. error=%r", coaching_error
+        )
+        coaching = _local_coaching(weakest_answer, startup, signals, scores)
+        source = "hybrid_claims_local"
+        model_ok = False
+        provider = "local"
+    else:
+        source = "hybrid_claims_nemotron"
+        model_ok = True
+        provider = "local+nvidia"
+
+    # Step 7: Assemble and return complete scorecard
+    result: dict[str, Any] = {
+        "overall": overall,
+        "overall_label": _score_label(overall),
+        "scores": scores,
+        "best_answer": best_answer,
+        "weakest_answer": weakest_answer,
+        "why_weak": why_weak,
+        "improved_answer": coaching["improved_answer"],
+        "improved_pitch": coaching["improved_pitch"],
+        "top_3_questions": coaching["top_3_questions"],
+        "concrete_signals_summary": concrete_signals_summary,
+        "model_ok": model_ok,
+        "provider": provider,
+        "model_mode": resolved_mode,
+        "scorecard_source": source,
+    }
+    if coaching_error and not model_ok:
+        result["model_error"] = coaching_error
+
+    logger.info(
+        "scoring_engine: hybrid scorecard complete — overall=%d source=%s signals=%d",
+        overall, source, signals.get("signal_count", 0),
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Session-aware fallback (used by api_handlers exception handler + local crash)
+# ---------------------------------------------------------------------------
+
+def build_session_aware_fallback_scorecard(
+    session: dict, signals: dict, error: str = ""
+) -> dict[str, Any]:
+    """Session-aware fallback when even local scoring crashes.
+
+    Uses actual user answers and extracted signals — never shows static EventRadar content.
+    """
+    startup = session.get("startup", {})
+    all_answers = signals.get("all_user_answers", [])
+    best_quotes = signals.get("best_user_quotes", [])
+    non_answers = signals.get("non_answers", [])
+
+    best_answer = best_quotes[0] if best_quotes else (all_answers[0] if all_answers else "No answers recorded.")
+    non_best = [a for a in all_answers if a != best_answer]
+    if non_answers:
+        weakest_answer = non_answers[0]
+    elif non_best:
+        weakest_answer = min(non_best, key=len)
+    else:
+        weakest_answer = all_answers[-1] if all_answers else "No answers recorded."
+
+    has_numbers    = bool(signals.get("numbers") or signals.get("user_counts"))
+    has_validation = bool(signals.get("validation"))
+    has_competitors= bool(signals.get("competitors"))
+    has_tech       = bool(signals.get("technical_mechanisms"))
+    has_revenue    = bool(signals.get("revenue_signals") or signals.get("pricing"))
+    has_colleges   = bool(signals.get("college_mentions"))
+    total          = len(all_answers)
+    non_ans_count  = len(non_answers)
+    engagement     = 1.0 - (non_ans_count / max(total, 1))
+
+    def _c(v: int) -> int:
+        return max(0, min(100, v))
+
+    clarity_score = _c(65 if (has_numbers and total > 1) else 52 if total > 2 else 35)
+    problem_score = _c(
+        72 if (has_validation and has_colleges) else
+        63 if has_validation else
+        55 if has_numbers else
+        45 if engagement > 0.7 else 30
+    )
+    market_score = _c(
+        68 if (has_numbers and has_competitors) else
+        55 if (has_numbers or has_competitors) else
+        38 if engagement > 0.6 else 22
+    )
+    diff_score = _c(
+        70 if (has_competitors and has_tech) else
+        55 if (has_competitors or has_tech) else
+        38 if engagement > 0.6 else 25
+    )
+    biz_score = _c(
+        65 if (has_revenue and has_numbers) else
+        52 if has_revenue else
+        38 if has_validation else
+        30 if engagement > 0.5 else 18
+    )
+    obj_score = _c(int(engagement * 65) + (8 if has_validation else 0) + (5 if has_numbers else 0))
+
+    scores = {
+        "clarity": _dimension(
+            clarity_score,
+            f"Local estimate from {total} answer(s). Scoring engine unavailable.",
+            best_answer[:160],
+            signals.get("numbers", [])[:3],
+        ),
+        "problem_understanding": _dimension(
+            problem_score,
+            "Based on validation/research evidence detected in answers."
+            + (" College mentions found." if has_colleges else ""),
+            (signals.get("validation") or [""])[0],
+            (signals.get("validation", []) + signals.get("college_mentions", []))[:3],
+        ),
+        "market_awareness": _dimension(
+            market_score,
+            "Based on numbers/metrics and competitor mentions in answers.",
+            (signals.get("numbers") or signals.get("competitors") or [""])[0],
+            (signals.get("numbers", []) + signals.get("competitors", []))[:3],
+        ),
+        "differentiation": _dimension(
+            diff_score,
+            "Based on competitor mentions and technical mechanism signals.",
+            (signals.get("competitors") or signals.get("technical_mechanisms") or [""])[0],
+            (signals.get("competitors", []) + signals.get("technical_mechanisms", []))[:3],
+        ),
+        "business_model": _dimension(
+            biz_score,
+            "Based on revenue/pricing signals detected in answers."
+            + (" No explicit price found." if not has_revenue else ""),
+            (signals.get("revenue_signals") or signals.get("pricing") or [""])[0],
+            (signals.get("revenue_signals", []) + signals.get("pricing", []))[:3],
+        ),
+        "objection_handling": _dimension(
+            obj_score,
+            f"{int(engagement * 100)}% substantive responses. {non_ans_count} non-answer turn(s) noted.",
+            best_answer[:160],
+            (signals.get("validation", []) + signals.get("numbers", []))[:3],
+        ),
+    }
+
+    overall = round(sum(d["score"] for d in scores.values()) / 6)
+    dim_sorted = sorted(scores.items(), key=lambda x: x[1]["score"])
+
+    return {
+        "overall": overall,
+        "overall_label": _score_label(overall),
+        "scores": scores,
+        "best_answer": best_answer,
+        "weakest_answer": weakest_answer,
+        "why_weak": "This answer lacked concrete evidence compared to your stronger responses.",
+        "improved_answer": _local_improved_answer(weakest_answer, startup, signals),
+        "improved_pitch": _local_improved_pitch(startup, signals),
+        "top_3_questions": _fallback_questions(dim_sorted, startup),
+        "concrete_signals_summary": {
+            "numbers":              signals.get("numbers", [])[:6],
+            "validation":           signals.get("validation", [])[:6],
+            "competitors":          signals.get("competitors", [])[:6],
+            "revenue_signals":      signals.get("revenue_signals", [])[:6],
+            "technical_mechanisms": signals.get("technical_mechanisms", [])[:6],
+        },
+        "model_ok": False,
+        "provider": "local",
+        "model_mode": "session_fallback",
+        "scorecard_source": "session_fallback",
+        **({"model_error": error} if error else {}),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Static mock scorecard (absolute last resort — no session available)
+# ---------------------------------------------------------------------------
+
+def mock_scorecard(session: dict) -> dict:
+    """Static mock. Use ONLY when session-aware fallback also cannot run."""
+    startup = session.get("startup", {})
+    history = session.get("history", [])
+    name = startup.get("name", "your startup")
+    user_messages = [m["content"] for m in history if m.get("role") == "user"]
+    best_answer = user_messages[0] if user_messages else "No answers recorded yet."
+    weakest_answer = user_messages[-1] if user_messages else "No answers recorded."
+
+    scores = {
+        "clarity": _dimension(64, f"Several answers stayed high-level without concrete proof.", weakest_answer[:160]),
+        "problem_understanding": _dimension(
+            76, f"Problem understanding was articulated for {name}.", startup.get("problem", "")[:160]
+        ),
+        "market_awareness": _dimension(67, "Competitors were named but differentiation was not sharp.", ""),
+        "differentiation": _dimension(63, "The AI angle needs a clearer moat beyond basic filtering.", ""),
+        "business_model": _dimension(61, "Revenue path and retention logic were not defended under pressure.", ""),
+        "objection_handling": _dimension(72, "You stayed in the fight but dodged the hardest follow-ups.", best_answer[:160]),
+    }
+    return {
+        "overall": 68,
+        "overall_label": _score_label(68),
+        "scores": scores,
+        "best_answer": best_answer,
+        "weakest_answer": weakest_answer,
+        "why_weak": "The answer was vague and lacked concrete evidence or numbers.",
+        "improved_answer": f"A stronger answer would anchor {name}'s claims in specific evidence.",
+        "improved_pitch": f"{name} addresses {startup.get('problem', 'a key pain point')}.",
+        "top_3_questions": [
+            "Why does this need AI instead of filters and sorted lists?",
+            "How will you get students to use this instead of existing alternatives?",
+            "What is your wedge for the first 100 active users on one campus?",
+        ],
+        "concrete_signals_summary": {
+            "numbers": [], "validation": [], "competitors": [],
+            "revenue_signals": [], "technical_mechanisms": [],
+        },
+        "model_ok": False,
+        "provider": "mock",
+        "model_mode": "mock_fallback",
+        "scorecard_source": "fallback",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Legacy full-Nemotron scorecard (kept for diagnostics — not main path)
+# ---------------------------------------------------------------------------
+
+def generate_real_scorecard(session: dict, model_mode: str | None = None) -> dict:
+    """Legacy: redirects to generate_claim_based_scorecard."""
+    return generate_claim_based_scorecard(session, model_mode)

core/session_manager.py

@@ -0,0 +1,77 @@
+"""In-memory session manager for pitch battles."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+SESSIONS: dict[str, dict[str, Any]] = {}
+
+
+def create_session(
+    startup: dict,
+    persona: str,
+    difficulty: str,
+    input_mode: str,
+) -> dict[str, Any]:
+    """Create a new pitch battle session."""
+    session_id = str(uuid.uuid4())
+    session = {
+        "session_id": session_id,
+        "startup": startup,
+        "persona": persona,
+        "difficulty": difficulty,
+        "input_mode": input_mode,
+        "round": 1,
+        "history": [],
+    }
+    SESSIONS[session_id] = session
+    return session
+
+
+def get_session(session_id: str) -> dict[str, Any] | None:
+    """Return a session by id, or None if missing."""
+    return SESSIONS.get(session_id)
+
+
+def append_user_message(session_id: str, message: str) -> None:
+    """Append a user message to session history."""
+    session = SESSIONS.get(session_id)
+    if not session:
+        return
+    session["history"].append({"role": "user", "content": message})
+
+
+def append_ai_message(session_id: str, message: str, attack_tag: str) -> None:
+    """Append an AI opponent message to session history."""
+    session = SESSIONS.get(session_id)
+    if not session:
+        return
+    session["history"].append(
+        {"role": "assistant", "content": message, "attack_tag": attack_tag}
+    )
+
+
+def increment_round(session_id: str) -> int:
+    """Increment and return the current round number."""
+    session = SESSIONS.get(session_id)
+    if not session:
+        return 0
+    session["round"] = session.get("round", 1) + 1
+    return session["round"]
+
+
+def get_history(session_id: str) -> list[dict[str, Any]]:
+    """Return conversation history for a session."""
+    session = SESSIONS.get(session_id)
+    if not session:
+        return []
+    return list(session.get("history", []))
+
+
+def reset_session(session_id: str) -> bool:
+    """Delete a session. Returns True if it existed."""
+    if session_id in SESSIONS:
+        del SESSIONS[session_id]
+        return True
+    return False

core/transcription_client.py

@@ -0,0 +1,13 @@
+"""Stub transcription client — faster-whisper fallback planned for Phase 7."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def health_check() -> dict[str, Any]:
+    return {
+        "status": "not_configured",
+        "provider": "local",
+        "message": "faster-whisper fallback planned for Phase 7",
+    }

core/vision_client.py

@@ -0,0 +1,13 @@
+"""Stub vision client — MiniCPM-V 4.6 deck critique planned for Phase 10."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def health_check() -> dict[str, Any]:
+    return {
+        "status": "not_configured",
+        "provider": "openbmb",
+        "message": "Vision/deck critique planned for Phase 10",
+    }

core/voice_transcriber.py

@@ -0,0 +1,13 @@
+"""Placeholder voice transcriber for Phase 9 integration."""
+
+from __future__ import annotations
+
+
+class VoiceTranscriber:
+    """Stub for future faster-whisper integration."""
+
+    def health_check(self) -> dict[str, str]:
+        return {
+            "status": "not_loaded",
+            "message": "Voice transcription will be added in Phase 9",
+        }

docs/BACKEND_API.md

@@ -0,0 +1,393 @@
+# PitchFight AI — Backend API Reference
+
+## 1. Important Note About Gradio Internal Endpoints
+
+When you run `python app.py` and open FastAPI/Swagger (`/docs`), you will see **many routes** that are **not** PitchFight AI product APIs, for example:
+
+- `/gradio_api/*` — config, queue, upload, streaming
+- `/queue/*` — Gradio job queue
+- `/upload` — Gradio file upload
+- `/static/*`, `/assets/*`, `/theme.css` — Gradio UI assets
+- Login, monitoring, and other framework runtime routes
+
+These are **automatically registered by Gradio** and are required for Gradio Server to work on Hugging Face Spaces. **Do not delete them.**
+
+**PitchFight AI’s real backend endpoints** are namespaced under **`/api/...`** plus **`/health`** and **`/`**.
+
+> Judge this project’s API design by `/api/*` and this document — not by the long Gradio-generated OpenAPI list.
+
+---
+
+## 2. Backend Design Principles
+
+| Principle | Detail |
+|---|---|
+| **Frontend never calls model providers** | No NVIDIA/OpenBMB keys in browser JS; only `/api/*` + `/health` |
+| **Backend owns model routing** | `core/model_router.py` (Phase 2+) — default `premium_nvidia` (Nemotron Omni 30B-A3B) |
+| **Backend owns session state** | `core/session_manager.py` |
+| **Backend owns scoring** | `core/scoring_engine.py` |
+| **Frontend sends actions, renders results** | Custom HTML/CSS/JS + `fetch()` |
+| **Secrets in env only** | `.env` locally, HF Space Secrets in deployment — never in frontend or repo |
+
+> **Strategy:** High-demo sponsor-model build. Off-the-Grid is not targeted. faster-whisper is transcription fallback only; OpenBMB MiniCPM modes are secondary/fallback paths.
+
+Shared logic lives in **`core/api_handlers.py`**. Both REST routes (`/api/...`) and Gradio `@app.api` wrappers call the same handler functions.
+
+---
+
+## 3. Clean Project Endpoints
+
+| Method | Path | Status | Purpose |
+|---|---|---|---|
+| `GET` | `/health` | **Implemented** | App health check |
+| `GET` | `/` | **Implemented** | Serve custom frontend |
+| `GET` | `/api/model-health` | **Implemented** (Phase 2) | Model provider config status (no keys) |
+| `POST` | `/api/load-sample` | **Implemented** | Load EventRadar AI demo startup |
+| `POST` | `/api/start-session` | **Implemented** | Start Pitch Battle session |
+| `POST` | `/api/chat-round` | **Implemented** | Send user answer, get AI pushback |
+| `POST` | `/api/end-battle` | **Implemented** | Generate scorecard |
+| `POST` | `/api/reset-session` | **Implemented** | Delete session |
+| `POST` | `/api/voice-pitch` | **Placeholder** | Voice pitch (reserved) |
+| `POST` | `/api/start-deal-session` | **Placeholder** | Deal Battle (reserved) |
+| `POST` | `/api/deck-critique` | **Placeholder** | Pitch deck critique (reserved) |
+
+### Gradio compatibility wrappers (same handlers)
+
+| Gradio `@app.api` name | Handler |
+|---|---|
+| `load_sample` | `handle_load_sample()` |
+| `start_session` | `handle_start_session()` |
+| `chat_round` | `handle_chat_round()` |
+| `end_battle` | `handle_end_battle()` |
+| `reset_session` | `handle_reset_session()` |
+
+---
+
+## 4. Endpoint Details
+
+### `GET /health`
+
+**Purpose:** Verify the server is running.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "app": "PitchFight AI",
+  "version": "0.1.0"
+}
+```
+
+---
+
+### `GET /api/model-health`
+
+**Purpose:** Return model provider configuration status. API keys are **never** included in the response.
+
+**Response:**
+
+```json
+{
+  "default_mode": "premium_nvidia",
+  "supported_modes": ["openbmb_omni", "premium_nvidia", "tiny_minicpm", "vision_deck", "whisper_fallback"],
+  "providers": {
+    "nvidia": {
+      "provider": "nvidia",
+      "configured": true,
+      "base_url": "https://integrate.api.nvidia.com/v1",
+      "model": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
+      "api_key_present": true,
+      "message": "NVIDIA client ready"
+    },
+    "minicpm": { "status": "not_configured", "provider": "openbmb", "message": "MiniCPM integration planned for Phase 9" },
+    "vision":  { "status": "not_configured", "provider": "openbmb", "message": "Vision/deck critique planned for Phase 10" },
+    "transcription": { "status": "not_configured", "provider": "local", "message": "faster-whisper fallback planned for Phase 7" }
+  }
+}
+```
+
+---
+
+### `GET /`
+
+**Purpose:** Serve `frontend/index.html` (custom battle arena UI).
+
+Static assets: `/frontend/styles.css`, `/frontend/script.js`, `/frontend/assets/*`
+
+---
+
+### `POST /api/load-sample`
+
+**Purpose:** Load the EventRadar AI sample startup into the form.
+
+**Request body:** none
+
+**Response:**
+
+```json
+{
+  "startup": {
+    "name": "EventRadar AI",
+    "problem": "...",
+    "target_users": "...",
+    "solution": "...",
+    "why_ai": "...",
+    "competitors": "...",
+    "traction": "...",
+    "ask": "..."
+  }
+}
+```
+
+---
+
+### `POST /api/start-session`
+
+**Purpose:** Start a new Pitch Battle session.
+
+**Request body:**
+
+```json
+{
+  "mode": "pitch_battle",
+  "persona": "hackathon_judge",
+  "difficulty": "high",
+  "input_mode": "text",
+  "model_mode": "premium_nvidia",
+  "startup": {
+    "name": "EventRadar AI",
+    "problem": "...",
+    "target_users": "...",
+    "solution": "...",
+    "why_ai": "...",
+    "competitors": "...",
+    "traction": "...",
+    "ask": "..."
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "session_id": "uuid",
+  "round": 1,
+  "pressure_level": "Medium",
+  "attack_tag": "User Pain",
+  "ai_message": "Students already lurk in WhatsApp groups..."
+}
+```
+
+---
+
+### `POST /api/chat-round`
+
+**Purpose:** Submit one founder answer and receive the next AI challenge.
+
+**Request body:**
+
+```json
+{
+  "session_id": "uuid",
+  "user_message": "We use AI to rank events for students."
+}
+```
+
+**Response:**
+
+```json
+{
+  "session_id": "uuid",
+  "round": 2,
+  "pressure_level": "Medium",
+  "attack_tag": "Demo Clarity",
+  "ai_message": "If I only saw a 30-second demo..."
+}
+```
+
+---
+
+### `POST /api/end-battle`
+
+**Purpose:** End the battle and return a scorecard.
+
+**Request body:**
+
+```json
+{
+  "session_id": "uuid"
+}
+```
+
+**Response:**
+
+```json
+{
+  "overall": 68,
+  "scores": {
+    "clarity": {
+      "score": 64,
+      "reason": "...",
+      "quote": "..."
+    }
+  },
+  "best_answer": "...",
+  "weakest_answer": "...",
+  "improved_answer": "...",
+  "improved_pitch": "...",
+  "top_3_questions": ["...", "...", "..."]
+}
+```
+
+---
+
+### `POST /api/reset-session`
+
+**Purpose:** Delete a session.
+
+**Request body:**
+
+```json
+{
+  "session_id": "uuid"
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "reset"
+}
+```
+
+---
+
+### `POST /api/voice-pitch` (placeholder)
+
+**Planned flow (Phase 7):** audio → Nemotron Omni (primary) → pitch context + opening question. Fallback: faster-whisper transcription → Nemotron or MiniCPM5-1B text path.
+
+**Response (current):**
+
+```json
+{
+  "status": "not_implemented",
+  "message": "Voice Mode endpoint is reserved. Primary path: Nemotron Omni voice; fallback: faster-whisper transcription."
+}
+```
+
+---
+
+### `POST /api/start-deal-session` (placeholder)
+
+**Response:**
+
+```json
+{
+  "status": "not_implemented",
+  "message": "Deal Battle endpoint is reserved and will be connected in a later phase."
+}
+```
+
+---
+
+### `POST /api/deck-critique` (placeholder)
+
+**Response:**
+
+```json
+{
+  "status": "not_implemented",
+  "message": "Deck critique endpoint is reserved and will be connected after MiniCPM-V vision integration."
+}
+```
+
+---
+
+## 5. Endpoint Flow Diagrams
+
+### Pitch Battle flow
+
+```mermaid
+flowchart TD
+    A[Frontend UI] --> B[/api/start-session]
+    B --> C[Session Manager]
+    C --> D[Persona Builder]
+    D --> E[Attack Tag Selector]
+    E --> F[Model Router]
+    F --> G[AI Response]
+    G --> A
+```
+
+### Scorecard flow
+
+```mermaid
+flowchart TD
+    A[Frontend UI] --> B[/api/end-battle]
+    B --> C[Session Manager]
+    C --> D[Scoring Engine]
+    D --> E[Model Router]
+    E --> F[JSON Parser]
+    F --> G[Scorecard Response]
+    G --> A
+```
+
+---
+
+## 6. Why Swagger Shows Many Routes
+
+Gradio Server is built on FastAPI. When the app launches, Gradio **automatically registers** internal endpoints for:
+
+- App configuration (`/gradio_api/config`, `/gradio_api/info`)
+- Request queueing (`/queue/join`, `/queue/data`)
+- File uploads (`/upload`)
+- Static assets and themes
+- Streaming, login checks, and monitoring
+
+These are **framework runtime routes**, not hand-written PitchFight product APIs. They exist so Gradio can host the app on Hugging Face Spaces with queuing, MCP, and ZeroGPU support.
+
+**You do not call or maintain those routes manually.** The custom frontend uses only `/api/*` and `/health`.
+
+---
+
+## 7. Final API Contract — Quick Examples
+
+### Load sample
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/load-sample
+```
+
+### Start session
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/start-session \
+  -H "Content-Type: application/json" \
+  -d '{"mode":"pitch_battle","persona":"hackathon_judge","difficulty":"high","input_mode":"text","model_mode":"premium_nvidia","startup":{"name":"Test","problem":"p","target_users":"u","solution":"s","why_ai":"a","competitors":"c","traction":"t","ask":"a"}}'
+```
+
+### Chat round
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/chat-round \
+  -H "Content-Type: application/json" \
+  -d '{"session_id":"<uuid>","user_message":"We use AI for ranking."}'
+```
+
+### End battle
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/end-battle \
+  -H "Content-Type: application/json" \
+  -d '{"session_id":"<uuid>"}'
+```
+
+### Reset session
+
+```bash
+curl -X POST http://127.0.0.1:7860/api/reset-session \
+  -H "Content-Type: application/json" \
+  -d '{"session_id":"<uuid>"}'
+```

docs/CLAUDE_PROJECT_CONTEXT.md

@@ -0,0 +1,299 @@
+# PitchFight AI — Claude Project Context
+
+> **Read this file before starting any implementation phase.**
+> Generated after full repository inspection on 2026-06-08.
+
+---
+
+## 1. Project Summary
+
+PitchFight AI is a voice-and-text AI sparring arena for student founders built for the Hugging Face **Build Small Hackathon** (Backyard AI track). The core use case: let founders get grilled by a realistic AI judge before they face real judges, mentors, investors, or sponsors. The AI does not give advice — it applies pressure, remembers prior answers, attacks vague claims, and scores the conversation.
+
+The project runs on **Gradio Server** (not default Gradio UI), hosts a **custom HTML/CSS/JS frontend**, and exposes a clean **`/api/*` REST layer**. All AI model calls are strictly backend-only. The frontend never touches any model provider API.
+
+---
+
+## 2. Current Strategy
+
+| Decision | Value |
+|---|---|
+| Hackathon track | Backyard AI |
+| Off-the-Grid | **Not targeted** — intentional |
+| Model cap | ≤32B parameters (all models comply) |
+| Default model mode | `premium_nvidia` |
+| Primary judge model | NVIDIA Nemotron 3 Nano Omni 30B-A3B |
+| Frontend model calls | **Never** — frontend calls `/api/*` only |
+| API keys | Backend `.env` locally; HF Space Secrets in deployment |
+| Target prizes | Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, Field Notes, Tiny Titan |
+| Current build status | Phase 1 complete (mock APIs running) |
+
+---
+
+## 3. Current Model Stack
+
+| Role | Model | Mode Key | Status |
+|---|---|---|---|
+| Primary judge (text, voice, scoring, rewrites) | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | `premium_nvidia` | **Live (Phase 2)** — client tested |
+| OpenBMB omni mode | `openbmb/MiniCPM-o-4_5` | `openbmb_omni` | Stub — Phase 9 |
+| Tiny fallback / Tiny Mode | `openbmb/MiniCPM5-1B` | `tiny_minicpm` | Stub — Phase 9 |
+| Pitch deck critique | `openbmb/MiniCPM-V-4.6` | `vision_deck` | Stub — Phase 10 |
+| Audio transcription fallback | `faster-whisper` (tiny or base) | `whisper_fallback` | Stub — Phase 7 |
+
+> **Reasoning model note:** `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` uses tokens for an internal chain-of-thought before writing `message.content`. Confirmed token defaults: opponent=500, scorecard=2000, rewrite=800.
+
+NVIDIA endpoint base URL: `https://integrate.api.nvidia.com/v1`
+
+All model calls must go through `core/model_router.py` → individual client files. No model provider URL or key must ever appear in frontend code.
+
+---
+
+## 4. Backend Architecture
+
+```
+app.py                        ← Gradio Server entrypoint
+  /health                     ← health check
+  /                           ← serves frontend/index.html
+  /api/load-sample            ← REST endpoint
+  /api/start-session          ← REST endpoint
+  /api/chat-round             ← REST endpoint
+  /api/end-battle             ← REST endpoint
+  /api/reset-session          ← REST endpoint
+  /api/voice-pitch            ← placeholder (Phase 7)
+  /api/start-deal-session     ← placeholder (Phase 8)
+  /api/deck-critique          ← placeholder (Phase 10)
+  @app.api wrappers           ← same handlers, Gradio client compat
+
+core/api_handlers.py          ← shared handler logic (REST + Gradio route)
+core/session_manager.py       ← in-memory session store (SESSIONS dict)
+core/persona_builder.py       ← builds system prompt per persona + startup
+core/attack_tags.py           ← attack tag taxonomy, round-based selection
+core/scoring_engine.py        ← mock scorecard (Phase 1); real model call planned Phase 5
+core/feedback_generator.py    ← mock rewrite logic (Phase 1); model call planned Phase 5
+core/json_utils.py            ← JSON extraction + safe_json_parse + fallback_scorecard()
+core/local_text_model.py      ← stub placeholder (Phase 1 only)
+core/voice_transcriber.py     ← stub placeholder (Phase 7)
+core/samples.py               ← get_sample_startup() (EventRadar AI)
+
+config/personas.json          ← persona metadata (ids, names, focus areas)
+config/attack_tags.json       ← attack tag reference (not yet used in code — code uses attack_tags.py)
+config/pitch_rubric.json      ← 6 dimensions + weights
+config/sample_startups.json   ← sample startup data
+
+ADDED in Phase 2:
+  model_router.py             ← routes tasks; premium_nvidia live; others stub
+  nvidia_client.py            ← NVIDIA Nemotron client; live, tested
+  minicpm_client.py           ← health_check stub (Phase 9)
+  vision_client.py            ← health_check stub (Phase 10)
+  transcription_client.py     ← health_check stub (Phase 7)
+```
+
+---
+
+## 5. Frontend Architecture
+
+File: `frontend/script.js`
+
+The frontend uses **`fetch()`** calls exclusively to `/api/*` backend routes. No model provider URLs or API keys exist in any frontend file. This is verified and correct.
+
+Key functions:
+- `apiPost(path, body)` — all API calls go through this helper
+- `loadSample()` → `POST /api/load-sample`
+- `startSession()` → `POST /api/start-session` (sends `model_mode: "premium_nvidia"`)
+- `sendMessage()` → `POST /api/chat-round`
+- `endBattle()` → `POST /api/end-battle`
+- `resetBattle()` → `POST /api/reset-session`
+- `renderScorecard(data)` — renders overall score, bars, rewrites, questions
+
+The `boot()` function calls `GET /health` on page load for backend availability check.
+
+Static assets served at `/frontend/*` via Gradio StaticFiles mount.
+
+---
+
+## 6. Real Product API Endpoints
+
+These are the only endpoints that matter for PitchFight as a product. Ignore Gradio-internal Swagger routes.
+
+| Method | Path | Status | Phase |
+|---|---|---|---|
+| GET | `/health` | Live (mock-free) | Phase 1 |
+| GET | `/` | Live | Phase 1 |
+| POST | `/api/load-sample` | Live (real config data) | Phase 1 |
+| POST | `/api/start-session` | Live (mock AI response) | Phase 1 |
+| POST | `/api/chat-round` | Live (mock AI response) | Phase 1 |
+| POST | `/api/end-battle` | Live (mock scorecard) | Phase 1 |
+| POST | `/api/reset-session` | Live | Phase 1 |
+| POST | `/api/voice-pitch` | Placeholder 501 | Phase 7 |
+| POST | `/api/start-deal-session` | Placeholder 501 | Phase 8 |
+| POST | `/api/deck-critique` | Placeholder 501 | Phase 10 |
+
+Gradio internal routes (`/gradio_api/*`, `/queue/*`, `/upload`, `/static/*`) are framework runtime routes registered automatically. **Do not call or maintain them as product APIs.**
+
+---
+
+## 7. Existing File Structure
+
+```
+Pitchfight/
+├── app.py                         ← Gradio Server + REST endpoints
+├── .env.example                   ← env template (complete, correct)
+├── .gitignore                     ← must include .env
+├── README.md                      ← HF Spaces metadata + project overview
+├── core/
+│   ├── __init__.py
+│   ├── api_handlers.py            ← shared handler logic
+│   ├── attack_tags.py             ← tag taxonomy + selector
+│   ├── feedback_generator.py      ← mock rewrite (Phase 1)
+│   ├── json_utils.py              ← JSON parse + fallback
+│   ├── local_text_model.py        ← stub (Phase 1)
+│   ├── persona_builder.py         ← system prompt builder
+│   ├── samples.py                 ← EventRadar AI sample
+│   ├── scoring_engine.py          ← mock scorecard (Phase 1)
+│   ├── session_manager.py         ← in-memory sessions
+│   └── voice_transcriber.py       ← stub (Phase 1)
+├── config/
+│   ├── attack_tags.json           ← reference (code uses attack_tags.py)
+│   ├── personas.json              ← persona metadata
+│   ├── pitch_rubric.json          ← 6-dimension rubric weights
+│   └── sample_startups.json       ← sample startup data
+├── frontend/
+│   ├── index.html
+│   ├── script.js                  ← fetch-only, /api/* calls
+│   ├── styles.css
+│   └── assets/
+└── docs/
+    ├── BACKEND_API.md             ← endpoint reference
+    ├── CLAUDE_PROJECT_CONTEXT.md  ← this file
+    ├── DEMO_NOTES.md              ← demo flow + prize talking points
+    ├── DOCUMENTATION.md           ← full project documentation
+    ├── FIELD_NOTES.md             ← build log
+    ├── MODELS_FINAL.md            ← model strategy
+    ├── PHASE_WISE_PLAN.md         ← 14-phase build plan
+    ├── PROMPTS.md                 ← prompt templates
+    └── TASK_TRACKER.md            ← phase + task status
+```
+
+**Missing from `core/` (needed Phase 2+):**
+- `model_router.py`
+- `nvidia_client.py`
+- `minicpm_client.py`
+- `vision_client.py`
+- `transcription_client.py`
+
+---
+
+## 8. Current Implementation Status
+
+### Working (Phase 1)
+- Gradio Server app starts and serves custom frontend
+- GET `/health` returns version + status
+- GET `/` serves `frontend/index.html`
+- POST `/api/load-sample` returns EventRadar AI startup dict from `samples.py`
+- POST `/api/start-session` creates in-memory session, returns mock opening question keyed by persona
+- POST `/api/chat-round` increments round, rotates attack tags, returns hardcoded mock follow-up per persona
+- POST `/api/end-battle` returns mock scorecard with static scores, real user quotes from session history
+- POST `/api/reset-session` deletes session from SESSIONS dict
+- Frontend flow: landing → setup (load sample or enter custom) → battle arena → scorecard
+- Error banners and loading overlay functional in frontend
+- Health check on boot functional
+
+### Mock / Placeholder
+- All AI opponent messages in `api_handlers.py` — hardcoded string lists per persona
+- All scorecard scores — hardcoded integers (overall: 68, clarity: 64, etc.)
+- `feedback_generator.py` — template string rewrites, no model call
+- `local_text_model.py` — stub, returns placeholder string
+- `voice_transcriber.py` — stub, returns not_loaded status
+- `/api/voice-pitch` — returns `{"status": "not_implemented"}`
+- `/api/start-deal-session` — returns `{"status": "not_implemented"}`
+- `/api/deck-critique` — returns `{"status": "not_implemented"}`
+
+### Missing (Phase 2+)
+- `core/model_router.py` — central routing logic
+- `core/nvidia_client.py` — NVIDIA Nemotron API calls
+- `core/minicpm_client.py` — MiniCPM-o and MiniCPM5-1B API/local calls
+- `core/vision_client.py` — MiniCPM-V 4.6 image/vision calls
+- `core/transcription_client.py` — faster-whisper audio fallback
+- Real AI response in `handle_chat_round` (replace hardcoded followups)
+- Real scoring in `handle_end_battle` (replace `mock_scorecard`)
+- Real rewrite in `feedback_generator` (replace template strings)
+- Voice audio handling in `/api/voice-pitch`
+- Deal battle logic in `/api/start-deal-session`
+- Image upload and critique in `/api/deck-critique`
+
+---
+
+## 9. Mock vs Real Components
+
+| Component | Mock or Real | Notes |
+|---|---|---|
+| Session management | **Real** | In-memory, uuid-based, correct |
+| Persona system prompt builder | **Real** | `persona_builder.py` builds full system prompt |
+| Attack tag rotator | **Real** | `attack_tags.py` rotates by round index |
+| Sample startup data | **Real** | EventRadar AI data loaded from `samples.py` |
+| Config JSON files | **Real** | personas, rubric, tags all present |
+| JSON utils | **Real** | Extraction + safe parse + fallback all coded |
+| `json_utils.fallback_scorecard()` | **Real** | Safe fallback ready |
+| Opening AI question | **Mock** | Hardcoded per persona in `api_handlers.py` |
+| Follow-up AI questions | **Mock** | Hardcoded list per persona, index by round |
+| Scorecard scores | **Mock** | All integers hardcoded in `scoring_engine.mock_scorecard()` |
+| Answer rewrite | **Mock** | Template string in `feedback_generator.py` |
+| Pitch rewrite | **Mock** | Template string in `feedback_generator.py` |
+| NVIDIA API client | **Real** | `core/nvidia_client.py` — live, tested Phase 2 |
+| Model router | **Real** | `core/model_router.py` — premium_nvidia live; others stub |
+| MiniCPM clients | **Stub** | `core/minicpm_client.py` — health_check only, Phase 9 |
+| Vision client | **Stub** | `core/vision_client.py` — health_check only, Phase 10 |
+| Whisper transcription | **Stub** | `core/transcription_client.py` — health_check only, Phase 7 |
+
+---
+
+## 10. Next Recommended Phase
+
+**Phase 3: Wire model_router into battle flow**
+
+Phase 2 is complete. NVIDIA Nemotron is live and tested. Next step is connecting `model_router.generate_opponent_response()` to the actual battle endpoints.
+
+Goals:
+1. In `core/api_handlers.py`: import `model_router` and `persona_builder`
+2. In `handle_start_session`: build system prompt, call `model_router.generate_opponent_response()`, fall back to mock if `ok=False`
+3. In `handle_chat_round`: build full message history, call `model_router.generate_opponent_response()`, fall back to mock if `ok=False`
+4. End-to-end test: full battle with live Nemotron responses
+5. Update docs
+
+Do **not** connect voice, deal battle, scoring, or deck critique in Phase 3.
+
+---
+
+## 11. Rules for Future Claude Code Work
+
+1. **Always read docs before implementing a phase.** Read `PHASE_WISE_PLAN.md`, this file, and `BACKEND_API.md` before touching code.
+2. **Never expose API keys in frontend.** No env reads, no hardcoded keys, no fetch calls to model provider URLs from frontend JS.
+3. **Never commit `.env`.** `.gitignore` must include `.env`. Only `.env.example` (empty values) goes to repo.
+4. **Keep frontend calls limited to `/api/*`.** The only external call from frontend is to `/health`. All AI calls go through backend `/api/*` routes.
+5. **Keep model calls backend-only.** All `openai.Client`, `requests.post`, or SDK calls to NVIDIA/OpenBMB must be in `core/` files only.
+6. **After each phase, update `docs/PHASE_WISE_PLAN.md`** with a status line marking the phase complete.
+7. **After each phase, update `docs/FIELD_NOTES.md`** with what changed, what worked, and what was learned.
+8. **After each phase, update `docs/BACKEND_API.md`** if any endpoint changed signature, status, or behavior.
+9. **After each phase, update `docs/MODELS_FINAL.md`** if the model strategy or routing changed.
+10. **Do not silently change architecture.** Any change to the API contract, session model, or model routing must be documented before implementation.
+11. **Preserve the working mock flow while replacing parts incrementally.** Never delete a working mock endpoint before its replacement is tested. The mock is the safety net.
+12. **Use `os.getenv()` only** for API key reads. Never use hardcoded fallback values for secrets. If the key is missing, log a warning and return a clear error — do not silently continue.
+13. **Do not add features outside the current phase scope.** One phase at a time. Phase 2 is model router only. Phase 3 is NVIDIA text only. Do not reach forward.
+14. **Test each model client independently** before wiring it into the session/handler flow.
+15. **`core/json_utils.py` already has `safe_json_parse` and `fallback_scorecard`.** Use them — do not rewrite JSON parsing logic elsewhere.
+
+---
+
+## 12. Documentation Update Rules
+
+After every phase:
+
+| Doc | What to update |
+|---|---|
+| `docs/PHASE_WISE_PLAN.md` | Mark phase status as Complete. Add date. |
+| `docs/FIELD_NOTES.md` | Add a build log entry: what changed, what worked, what surprised you. |
+| `docs/BACKEND_API.md` | Update endpoint status column if a placeholder became real. |
+| `docs/MODELS_FINAL.md` | Update model-to-file mapping if new client files were created or routes changed. |
+| `docs/TASK_TRACKER.md` | Move completed tasks to done; update current phase and next tasks. |
+| `docs/CLAUDE_PROJECT_CONTEXT.md` | Update "Current Implementation Status" and "Mock vs Real Components" sections. |
+
+Do **not** update docs prophylactically for future phases. Only document what is actually implemented.

docs/DEMO_NOTES.md

@@ -0,0 +1,48 @@
+# PitchFight AI — Demo Notes
+
+## Strategic Demo Positioning
+
+PitchFight AI is a **high-demo sponsor-model build** — not Off-the-Grid. Lead with voice, pressure, and scorecard quality. Mention NVIDIA Nemotron Omni and OpenBMB MiniCPM modes as sponsor-aligned small models under 32B.
+
+## Full Demo Flow (Target Build)
+
+1. Open the app — custom battle arena UI (not default Gradio).
+2. Show **model mode badge** (Premium Nemotron / OpenBMB Omni / Tiny MiniCPM).
+3. **Text path:** Load EventRadar AI → Hackathon Judge → Enter Arena → get grilled → End Battle → scorecard.
+4. **Voice path:** Record spoken pitch → Nemotron interprets → first hard question → continue battle.
+5. **Deal Battle:** Sponsorship or salary negotiation scenario → deal-specific scorecard.
+6. **Deck critique (if built):** Upload slide screenshot → 3 judge questions.
+7. **Retry:** Retry weakest question → show improvement.
+
+## Phase 1 Demo Flow (Current)
+
+1. Open the app.
+2. Click **Load Demo Startup** (EventRadar AI).
+3. Select **Hackathon Judge**.
+4. Click **Enter the Arena**.
+5. Answer weakly (e.g., "We use AI to rank events better").
+6. Watch mock AI push back with attack tag + pressure level.
+7. Click **End Battle** after 2–3 rounds.
+8. Show scorecard: overall, bars, rewrites, top prep questions.
+
+## Talking Points
+
+- Custom Gradio Server frontend + `@app.api` backend.
+- All model calls backend-only; keys in HF Space Secrets.
+- ≤32B models: Nemotron Omni, MiniCPM-o, MiniCPM5-1B, MiniCPM-V.
+- Voice + multimodal judging as differentiator.
+- Rubric-based scorecard with quotes and rewrites.
+- Off-the-Grid **not** claimed — demo quality is the goal.
+
+## Prize Alignment Talking Points
+
+| Prize | Hook |
+|---|---|
+| Backyard AI | Student founders, real pressure practice |
+| Best Demo | Voice pitch → grill → scorecard in one flow |
+| Best Agent | Persona + memory + attack tags + scoring loop |
+| Off-Brand | Custom HTML/CSS/JS arena UI |
+| NVIDIA Nemotron Quest | Premium voice/multimodal judge |
+| OpenBMB Awards | MiniCPM-o / 5-1B / V modes |
+| Sharing is Caring | Public prompts, rubrics, attack tags |
+| Field Notes | Build story post-deployment |

docs/DOCUMENTATION.md

@@ -0,0 +1,1447 @@
+# ⚔️ PitchFight AI — Final Hackathon-Aligned Documentation
+
+## A Voice-and-Text AI Sparring Arena for Student Founders (≤32B Models)
+
+> **Your first tough pitch should not be in front of a real judge.**  
+> **Normal AI assistants give advice. PitchFight AI creates pressure.**
+
+### Strategy Update (Current Build)
+
+This documentation reflects the **high-demo sponsor-model strategy**. PitchFight AI prioritizes demo strength, model quality, and sponsor alignment (NVIDIA Nemotron Omni, OpenBMB MiniCPM) while staying under the **≤32B** Build Small Hackathon rule.
+
+> **Off-the-Grid is not targeted.** Premium default model mode is **NVIDIA Nemotron Omni** (backend-only). API keys live in `.env` locally / HF Space Secrets in deployment — never in the frontend.
+
+See also: [`PHASE_WISE_PLAN.md`](PHASE_WISE_PLAN.md) · [`MODELS_FINAL.md`](MODELS_FINAL.md) · [`BACKEND_API.md`](BACKEND_API.md)
+
+PitchFight AI exposes **clean custom project APIs under `/api/...`**. Gradio internal routes may appear in OpenAPI/Swagger, but they are **framework runtime routes**, not product endpoints.
+
+---
+
+## 1. Project Overview
+
+**PitchFight AI** is a Hugging Face Spaces + Gradio Server application that helps student founders practice high-pressure startup pitching before facing real judges, mentors, investors, sponsors, recruiters, or clients.
+
+The project is built for the **Backyard AI** track of the Build Small Hackathon. The target user is intentionally narrow:
+
+> **Student founders and hackathon builders who know their project, but freeze when someone asks hard questions.**
+
+PitchFight AI turns pitch practice into a realistic AI sparring arena. The AI does not behave like a generic assistant. It behaves like a skeptical counterpart, asks tough follow-up questions, remembers previous answers, detects weak claims, scores the conversation, and rewrites the weakest answer into a stronger response.
+
+---
+
+## 2. Hackathon Rule Alignment
+
+This section is intentionally explicit so the project does not violate the hackathon constraints.
+
+### Required Rules
+
+| Rule | How PitchFight AI Complies |
+|---|---|
+| **Small Models Only** | All models stay under the 32B parameter cap: Nemotron 3 Nano Omni (~30B), MiniCPM-o, MiniCPM5-1B, MiniCPM-V 4.6. |
+| **Built on Gradio** | Gradio Server app hosted as a Hugging Face Space with custom HTML/CSS/JS frontend. |
+| **Show, Don’t Tell** | Demo-first: pitch battle, voice mode, deal battle, scorecard — runnable in the Space. |
+| **No Frontend Model Calls** | Browser calls only `/api/...` endpoints via `fetch()`; model APIs are backend-only. |
+
+### Sponsor-Model / High-Demo Strategy
+
+The **default submitted build** prioritizes the strongest demonstrative experience:
+
+- **NVIDIA Nemotron Omni** — primary premium judge (text, voice, multimodal, scoring).
+- **OpenBMB MiniCPM** — MiniCPM-o (omni), MiniCPM5-1B (tiny/fallback), MiniCPM-V 4.6 (deck critique).
+- **faster-whisper** — backup local transcription when Omni voice path is unavailable.
+- **No browser-side model API calls** — all keys in HF Space Secrets / backend `.env`.
+- **No OpenAI or unrelated cloud APIs** in the default flow.
+
+### Off-the-Grid Position
+
+> **Off-the-Grid is intentionally not targeted.** Sponsor/model APIs are used for demo quality. The project instead targets Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, and Field Notes.
+
+### Final Compliance Position
+
+> **PitchFight AI follows hackathon core rules: ≤32B models, Gradio/HF Spaces, demo-first execution, backend-only inference with secrets managed server-side.**
+
+---
+
+## 3. Core Problem
+
+Most student founders prepare their pitch by:
+
+- Reading pitch tips online
+- Practicing alone
+- Showing their idea to friends who say “sounds good”
+- Making slides but not preparing for hard Q&A
+
+The first real pressure often happens during judging, mentoring, investor review, or sponsorship calls. That is exactly when many students freeze.
+
+### Gap
+
+There is no easy, low-cost, always-available sparring partner that can simulate:
+
+- A skeptical hackathon judge
+- A technical evaluator
+- A hard investor
+- A sponsor asking for ROI
+- A recruiter or client pushing back
+
+### PitchFight AI’s Solution
+
+PitchFight AI creates a **pressure simulation loop**:
+
+1. User enters startup/project context.
+2. User chooses an AI opponent.
+3. AI opponent asks one sharp question at a time.
+4. User responds under pressure.
+5. AI follows up on weak or vague answers.
+6. App generates a scorecard and improved answer.
+
+---
+
+## 4. Final Product Scope
+
+### Primary Mode: Pitch Battle
+
+The user defends their startup or hackathon project against a persona-locked AI opponent.
+
+#### Personas
+
+| Persona | Role | What They Attack |
+|---|---|---|
+| **Skeptical VC** | Investor-style evaluator | Market, moat, revenue, defensibility, retention |
+| **Technical Judge** | Engineering evaluator | AI necessity, architecture, scalability, feasibility |
+| **Hackathon Judge** | Competition evaluator | Novelty, demo clarity, MVP strength, real-world usefulness |
+
+### Secondary Mode: Deal Battle
+
+The user practices negotiation scenarios useful for student founders and early-career builders.
+
+#### Scenarios
+
+| Scenario | Counterpart |
+|---|---|
+| Startup Sponsorship Ask | Tough sponsor |
+| Internship Salary Negotiation | Strict HR recruiter |
+| Freelance Client Pricing | Budget-conscious client |
+| Equity Negotiation | Investor negotiating hard |
+
+### Voice Mode
+
+Voice Mode allows the user to speak their pitch instead of typing it.
+
+For the MVP, Voice Mode is intentionally simple and reliable:
+
+```text
+User records pitch audio
+        ↓
+Backend /api/voice-pitch (frontend never calls model APIs)
+        ↓
+Primary: NVIDIA Nemotron Omni interprets audio + asks first hard question
+        ↓
+Fallback: faster-whisper transcribes → Nemotron or MiniCPM5-1B text path
+        ↓
+User continues by text or voice
+        ↓
+Scorecard includes voice-derived structure and conciseness signals
+```
+
+Founders normally pitch out loud; the premium voice path uses Nemotron Omni backend-only, with faster-whisper as transcription fallback only.
+
+---
+
+## 5. What Makes This a Strong Hackathon Project
+
+PitchFight AI is designed around the hackathon’s judging taste: runnable, specific, useful, delightful, and more than a chatbot wrapper.
+
+### Runnable Gradio Space
+
+The final app is deployed as a Hugging Face Space using Gradio.
+
+### Clear Purpose
+
+The app has one clear mission:
+
+> Help student founders survive tough pitch and negotiation conversations before the real moment.
+
+### Useful + Delightful
+
+Useful: improves pitch readiness.  
+Delightful: feels like entering a battle arena instead of filling a boring form.
+
+### More Than a Chatbot Wrapper
+
+PitchFight AI includes:
+
+- Startup context intake
+- Persona selection
+- Round-based battle flow
+- Pressure level
+- Attack tags
+- Conversation memory
+- Voice pitch mode
+- Rubric-based scoring
+- Weakest answer detection
+- Improved answer rewrite
+- Final pitch rewrite
+- Scorecard screen
+
+### Small Model Showcase
+
+The project uses compact models strategically rather than relying on one huge model. The intelligence comes from:
+
+- Strong persona prompts
+- Memory
+- Role consistency
+- Attack-tag routing
+- Rubric scoring
+- faster-whisper transcription fallback (when Omni voice path is unavailable)
+- Feedback generation
+
+---
+
+## 6. Final System Architecture
+
+```mermaid
+flowchart TD
+    A[Student Founder] --> B[Custom Web UI — fetch to /api/* only]
+
+    B --> C{Input Mode}
+    C -->|Text Pitch| D[Startup Context Form]
+    C -->|Voice Pitch| E[Browser Audio Recorder]
+
+    D --> H[Session Manager]
+    E --> VP[/api/voice-pitch]
+    VP --> F[NVIDIA Nemotron Omni — primary voice path]
+    VP --> W[faster-whisper — transcription fallback only]
+    F --> H
+    W --> H
+
+    H --> I[Persona Prompt Builder]
+    I --> J[Attack Tag Selector]
+    J --> K[Battle Engine]
+
+    K --> MR[Model Router]
+    MR --> L1[NVIDIA Nemotron Omni — default premium judge]
+    MR --> L2[MiniCPM-o 4.5 — OpenBMB omni mode]
+    MR --> L3[MiniCPM5-1B — tiny / API-failure fallback]
+    MR --> L4[MiniCPM-V 4.6 — deck critique]
+    L1 --> M[AI Opponent Response]
+    L2 --> M
+    L3 --> M
+    M --> B
+
+    H --> N[Scoring Engine]
+    N --> MR
+    MR --> O[Structured Scorecard JSON]
+    O --> P[JSON Parser + Fallback Handler]
+    P --> Q[Feedback Generator]
+    Q --> R[Scorecard + Improved Answer]
+    R --> B
+```
+
+### Simple Explanation
+
+- The **custom frontend** handles the arena UI and calls only **`/api/...`** endpoints — never model provider APIs.
+- **Gradio Server** exposes backend APIs and serves the custom frontend.
+- The **Session Manager** stores startup details, chosen persona, round count, attack tags, and conversation history.
+- The **Persona Prompt Builder** creates the opponent behavior.
+- The **Attack Tag Selector** decides what kind of pressure the AI should apply next.
+- The **Model Router** routes inference to **NVIDIA Nemotron Omni** by default, with OpenBMB MiniCPM modes and MiniCPM5-1B fallback.
+- **faster-whisper** is backup transcription only when the Omni voice path is unavailable.
+- API keys live in **HF Space Secrets** / backend `.env` only — never in frontend code.
+- The **Scorecard UI** shows what went well, what failed, and how to improve.
+
+---
+
+## 7. User Workflow Diagram
+
+```mermaid
+flowchart LR
+    A[Open PitchFight AI] --> B[Choose Mode]
+    B --> C[Pitch Battle]
+    B --> D[Deal Battle]
+
+    C --> E[Enter Startup Context]
+    D --> F[Enter Negotiation Context]
+
+    E --> G[Choose Opponent]
+    F --> G
+
+    G --> H[Choose Text or Voice Input]
+    H --> I[AI Opens With Hard Question]
+    I --> J[User Responds]
+    J --> K[AI Selects Attack Tag]
+    K --> L[AI Pushes Back]
+    L --> J
+
+    J --> M[End Battle]
+    M --> N[Scorecard]
+    N --> O[Weakest Answer]
+    O --> P[Improved Version]
+    P --> Q[Retry or Start New Battle]
+```
+
+---
+
+## 8. Final Model Strategy
+
+The core model table is kept intentionally small. Every model listed here has a real job in the submitted app.
+
+| Model | Type | Where Used | Why Used |
+|---|---|---|---|
+| **NVIDIA Nemotron 3 Nano Omni** | Premium multimodal LLM (≤30B) | Primary judge: pitch battle, voice, deal battle, scoring, rewrites | Best demo quality; NVIDIA Nemotron Quest alignment |
+| **MiniCPM-o 4.5** | OpenBMB omni model | OpenBMB sponsor mode, multimodal fallback | OpenBMB Awards alignment |
+| **MiniCPM5-1B** | Tiny text LLM | Tiny Mode, API failure fallback | Speed + Tiny Titan eligibility |
+| **MiniCPM-V 4.6** | Vision model | Pitch deck / slide critique | Image-based judge questions |
+| **faster-whisper (tiny/base)** | Local STT | Voice fallback transcription | Reliable backup when Omni voice path fails |
+
+### Fallback Model Note
+
+`core/model_router.py` routes to **Tiny MiniCPM5-1B** or **whisper_fallback** when premium APIs timeout, fail, or keys are missing. UI shows active mode badge (Premium Nemotron / OpenBMB Omni / Tiny MiniCPM).
+
+---
+
+## 9. Exact Use of Each Model
+
+### 9.1 NVIDIA Nemotron Omni — Primary Premium Model
+
+Used for:
+
+- AI opponent responses and follow-ups
+- Voice pitch interpretation and first hard question
+- Deal battle counterpart dialogue
+- Scorecard generation (structured JSON)
+- Weakest answer rewrite and 60-second pitch rewrite
+- Optional multimodal deck + spoken pitch critique
+
+#### Backend Client
+
+`core/nvidia_client.py` — secure calls via `NVIDIA_API_KEY` and `NVIDIA_BASE_URL`. Never exposed to frontend.
+
+### 9.1b MiniCPM Models — OpenBMB + Fallback
+
+**MiniCPM-o 4.5** — OpenBMB omni mode. **MiniCPM5-1B** — tiny/fallback text. **MiniCPM-V 4.6** — slide critique.
+
+#### Runtime Options
+
+| Runtime | Use Case |
+|---|---|
+| OpenBMB API / HF inference | Primary OpenBMB sponsor path |
+| Local `transformers` / quantized | Tiny Mode on Space hardware if needed |
+
+#### Suggested Settings
+
+| Task | Temperature | Max Tokens |
+|---|---:|---:|
+| Opponent response | 0.7–0.8 | 180–260 |
+| Scorecard | 0.1–0.3 | 900–1400 |
+| Rewrite weak answer | 0.4–0.5 | 400–600 |
+| Final pitch rewrite | 0.5–0.6 | 400–700 |
+
+---
+
+### 9.2 Whisper Tiny/Base — Local Voice Input
+
+Used for:
+
+- Spoken pitch transcription
+- Spoken answer transcription
+- Generating a transcript for the text battle engine
+- Voice add-on metrics based on transcript structure
+
+#### Voice Flow (Primary)
+
+```text
+Browser records audio
+  → /voice_pitch API
+  → NVIDIA Nemotron Omni (audio + prompt)
+  → structured pitch context + first hard question
+  → Pitch Battle continues (voice or text)
+```
+
+#### Voice Flow (Fallback)
+
+```text
+Browser records audio
+  → faster-whisper local transcription
+  → transcript → selected text model (Nemotron or MiniCPM5-1B)
+  → normal Pitch Battle flow
+```
+
+---
+
+### 9.3 Pitch Deck Critique — MiniCPM-V / Nemotron Vision
+
+Used for:
+
+- Slide screenshot upload via `/deck_critique`
+- Claim extraction and clarity critique
+- Three judge prep questions per slide
+
+Primary: **MiniCPM-V 4.6**. Alternate: Nemotron Omni vision path.
+
+---
+
+## 10. Tools and Their Exact Usage
+
+| Tool / Platform | Use in PitchFight AI |
+|---|---|
+| **Hugging Face Spaces** | Final deployment platform |
+| **Gradio Server** | Gradio backend server with custom route support |
+| **FastAPI `/api/*` routes** | Product endpoints: `/api/start-session`, `/api/chat-round`, `/api/end-battle`, etc. |
+| **Gradio `@app.api` wrappers** | Compatibility aliases calling the same `core/api_handlers.py` functions |
+| **Custom HTML/CSS/JS** | Makes the UI look like a battle arena instead of default Gradio |
+| **Browser `fetch()`** | Frontend calls `/api/*` endpoints only — never model provider APIs |
+| **faster-whisper** | Audio transcription fallback when Nemotron Omni voice path is unavailable |
+| **Hugging Face Hub** | Model download and project sharing |
+| **HF Space Secrets** | NVIDIA, OpenBMB, and HF tokens for backend-only inference (never exposed to frontend) |
+| **GitHub / HF repo** | Version control and project sharing |
+| **Mermaid diagrams** | Architecture and workflow documentation |
+| **Cursor Agent** | Frontend implementation and UI polish |
+| **Claude Code** | File generation, backend modules, refactoring |
+| **ChatGPT** | Planning, architecture, prompt design, debugging strategy, documentation |
+
+---
+
+## 11. Backend API Design
+
+The frontend should never call model runtime code directly. All model calls go through the Python backend.
+
+### Correct Flow
+
+```text
+Browser UI → /api/* (fetch) → api_handlers → model_router → NVIDIA / OpenBMB / whisper clients
+```
+
+### Wrong Flow
+
+```text
+Browser UI → External model API directly
+```
+
+This would expose API keys. All model calls must stay on the backend.
+
+---
+
+### 11.1 `/start_session`
+
+Starts a new battle session.
+
+#### Input
+
+```json
+{
+  "mode": "pitch_battle",
+  "persona": "hackathon_judge",
+  "difficulty": "high",
+  "input_mode": "text",
+  "startup": {
+    "name": "EventRadar AI",
+    "problem": "Students miss hackathons and tech events because discovery is scattered.",
+    "target_users": "College students and early-stage builders",
+    "solution": "AI-powered event matching based on goals, skills, location, and urgency",
+    "why_ai": "The model ranks and explains relevance instead of just listing events",
+    "competitors": "Luma, LinkedIn Events, WhatsApp groups",
+    "traction": "Prototype with scraped event data and ranking logic",
+    "ask": "Hackathon prize and mentor feedback"
+  }
+}
+```
+
+#### Output
+
+```json
+{
+  "session_id": "abc123",
+  "round": 1,
+  "pressure_level": "High",
+  "attack_tag": "AI Justification",
+  "ai_message": "Why does this need AI? A sorted event list with filters seems enough. What is the intelligence here?"
+}
+```
+
+---
+
+### 11.2 `/chat_round`
+
+Processes one user answer and returns the next AI pushback.
+
+#### Input
+
+```json
+{
+  "session_id": "abc123",
+  "user_message": "The AI ranks events based on the student's profile and explains why each event matters."
+}
+```
+
+#### Output
+
+```json
+{
+  "round": 2,
+  "pressure_level": "High",
+  "attack_tag": "Retention",
+  "ai_message": "That explains matching, not retention. Why would a student return every week instead of checking once before placement season?"
+}
+```
+
+---
+
+### 11.3 `/voice_pitch`
+
+Accepts an audio file. Primary path: Nemotron Omni voice interpretation. Fallback: faster-whisper transcription.
+
+#### Input
+
+```json
+{
+  "audio_file": "pitch.wav",
+  "persona": "skeptical_vc"
+}
+```
+
+#### Output
+
+```json
+{
+  "transcript": "We are building EventRadar AI...",
+  "detected_startup_context": {
+    "name": "EventRadar AI",
+    "problem": "students miss events",
+    "solution": "AI event matching"
+  },
+  "opening_question": "You are describing discovery, but where is the urgency? Why is this painful enough for students to change behavior?"
+}
+```
+
+Implementation detail:
+
+- **Primary:** audio sent to NVIDIA Nemotron Omni via backend; model extracts pitch context and opening question.
+- **Fallback:** faster-whisper transcribes locally; transcript routed to Nemotron or MiniCPM5-1B text path.
+- If context extraction is uncertain, the UI asks the user to quickly edit the detected fields before the battle starts.
+
+---
+
+### 11.4 `/end_battle`
+
+Scores the conversation.
+
+#### Input
+
+```json
+{
+  "session_id": "abc123"
+}
+```
+
+#### Output
+
+```json
+{
+  "overall": 68,
+  "scores": {
+    "clarity": {
+      "score": 76,
+      "reason": "The user explained the workflow clearly but took too long to state the core value.",
+      "quote": "It ranks events based on a student's profile."
+    },
+    "problem_understanding": {
+      "score": 70,
+      "reason": "The user described the problem but did not provide evidence of frequency or severity.",
+      "quote": "Students miss hackathons because discovery is scattered."
+    }
+  },
+  "best_answer": {
+    "quote": "The app explains why each event is relevant instead of only listing it.",
+    "why": "This differentiated the product from a basic directory."
+  },
+  "weakest_answer": {
+    "quote": "Students will use it because it is helpful.",
+    "why": "This answer was vague and did not address retention or urgency."
+  },
+  "improved_answer": "Students return because the system continuously tracks deadlines, skill fit, team requirements, and local event updates. It becomes a weekly opportunity radar, not a one-time event list.",
+  "improved_pitch": "EventRadar AI helps students discover the right hackathons and tech events by matching opportunities to their skills, goals, location, and urgency. Unlike static event lists, it explains why each event matters and helps students act before deadlines.",
+  "top_3_questions": [
+    "Why does this need AI instead of filters?",
+    "What makes users return weekly?",
+    "How will you get your first 100 active users?"
+  ]
+}
+```
+
+---
+
+## 12. Attack Tag Taxonomy
+
+Attack tags make PitchFight AI feel structured instead of random. The AI should rotate through known pressure points based on the selected persona and the user’s previous answer.
+
+### 12.1 Skeptical VC Attack Tags
+
+| Attack Tag | What It Tests | Example Question |
+|---|---|---|
+| Market Size | Whether the opportunity is big enough | “How many people have this problem badly enough to pay or change behavior?” |
+| Moat | Whether the idea is defensible | “What stops a larger platform from copying this in a week?” |
+| Retention | Whether users come back | “Why would someone open this again after the first use?” |
+| Revenue Logic | Whether there is a path to money/value | “Who pays, how much, and why would they keep paying?” |
+| First 100 Users | Whether acquisition is realistic | “How exactly do you get the first 100 active users without paid ads?” |
+| Why Now | Whether timing is convincing | “Why is this urgent now instead of two years ago or two years later?” |
+| Competition | Whether existing alternatives are understood | “Why does your user choose this over what they already do today?” |
+
+### 12.2 Technical Judge Attack Tags
+
+| Attack Tag | What It Tests | Example Question |
+|---|---|---|
+| AI Justification | Whether AI is actually needed | “What does the model do that filters or rules cannot?” |
+| Architecture | Whether the system design is clear | “Where exactly does inference happen, and what data flows through it?” |
+| Scalability | Whether the system can grow | “What breaks first when 100 users become 10,000?” |
+| Latency | Whether the UX is practical | “How long does one response take, and what happens when it is slow?” |
+| Data Quality | Whether input data is reliable | “Where does your data come from, and how do you handle missing or wrong data?” |
+| Failure Mode | Whether the team knows what can go wrong | “What is the worst wrong output your system can produce?” |
+| Simpler Alternative | Whether the build is overengineered | “Could this be done with a form and rules? Why is your system better?” |
+
+### 12.3 Hackathon Judge Attack Tags
+
+| Attack Tag | What It Tests | Example Question |
+|---|---|---|
+| Novelty | Whether the project is memorable | “I have seen similar ideas. What is the one thing I will remember?” |
+| Demo Clarity | Whether the demo lands quickly | “Can you show the value in 30 seconds?” |
+| MVP Strength | Whether the prototype actually works | “What part is fully working right now, not just planned?” |
+| User Pain | Whether the problem is real | “Who exactly has this problem, and how do you know?” |
+| AI Load-Bearing | Whether AI is central | “If I remove the model, does the product collapse or still work?” |
+| Backyard Fit | Whether it helps a real person | “Who used this, and what got better for them?” |
+| Practical Impact | Whether it matters beyond the demo | “What changes for the user after using this?” |
+
+### 12.4 Deal Battle Attack Tags
+
+| Attack Tag | What It Tests | Example Question |
+|---|---|---|
+| Anchoring | Whether the user sets a clear position | “What number are you asking for, and why that number?” |
+| Evidence | Whether claims are backed by proof | “What proof do you have that you are worth that ask?” |
+| Concession | Whether the user gives up too early | “If I say no, what do you offer without lowering the value?” |
+| Mutual Value | Whether both sides benefit | “Why is this good for me, not just for you?” |
+| Closing | Whether the user moves toward action | “What exact next step are you asking me to agree to?” |
+
+---
+
+## 13. Core Prompt Design
+
+### 13.1 Opponent System Prompt
+
+```text
+You are {persona_name}, a realistic evaluator speaking to a student founder.
+
+Your job is not to encourage. Your job is to pressure-test the founder's thinking.
+
+Startup context:
+- Name: {name}
+- Problem: {problem}
+- Target users: {target_users}
+- Solution: {solution}
+- Why AI: {why_ai}
+- Competitors: {competitors}
+- Traction: {traction}
+- Ask: {ask}
+
+Current attack tag: {attack_tag}
+
+Rules:
+1. Ask one sharp question at a time.
+2. Keep responses under 4 sentences.
+3. Reference the founder's previous answer.
+4. Do not give advice during the battle.
+5. Do not say "great answer", "interesting", or "that makes sense".
+6. If the answer is vague, attack the vague part.
+7. If the answer is strong, raise the difficulty.
+8. Stay in character.
+9. Be firm, realistic, and useful — not abusive.
+10. Your response must match the current attack tag.
+```
+
+---
+
+### 13.2 Scoring Prompt
+
+```text
+You watched a pitch battle between a student founder and an AI evaluator.
+
+Score the founder on:
+1. Clarity
+2. Problem Understanding
+3. Market Awareness
+4. Differentiation
+5. Business Model
+6. Objection Handling
+
+For each dimension:
+- Give a score from 0 to 100
+- Mention the exact quote that influenced the score
+- Give one specific reason
+
+Then identify:
+- Best answer
+- Weakest answer
+- Why the weak answer failed
+- Improved version of the weak answer
+- Improved 60-second pitch
+- Top 3 questions to prepare next
+
+Return valid JSON only.
+```
+
+---
+
+## 14. Scoring Rubric
+
+### Pitch Battle
+
+| Dimension | Weight | What It Measures |
+|---|---:|---|
+| Clarity | 15% | Can a judge understand the idea quickly? |
+| Problem Understanding | 20% | Did the founder prove the pain is real? |
+| Market Awareness | 15% | Do they know who the first users are? |
+| Differentiation | 20% | Why does this beat existing options? |
+| Business Model | 15% | Is there a path to value or revenue? |
+| Objection Handling | 15% | Did they answer directly or dodge? |
+
+### Deal Battle
+
+| Dimension | Weight | What It Measures |
+|---|---:|---|
+| Anchoring | 20% | Did the user set a clear position? |
+| Evidence Usage | 20% | Did they support the ask with proof? |
+| Confidence | 15% | Did they hold ground under pressure? |
+| Empathy | 15% | Did they understand the other side’s constraints? |
+| Concession Handling | 15% | Did they avoid giving up too fast? |
+| Closing | 15% | Did they move toward a clear next step? |
+
+### Voice Mode Add-On Metrics
+
+| Dimension | What It Measures |
+|---|---|
+| Structure | Did the spoken pitch have a clear beginning, middle, and ask? |
+| Conciseness | Did the user avoid rambling? |
+| Confidence Signals | Did the transcript show hesitation or unclear phrasing? |
+| Directness | Did the user answer the question directly? |
+
+---
+
+## 15. JSON Parsing and Fallback Strategy
+
+Small models can return malformed JSON. The scoring engine must handle this gracefully.
+
+### Fallback Pipeline
+
+```text
+1. Try direct JSON parse.
+        ↓
+2. If parse fails, extract substring from first `{` to last `}` and parse again.
+        ↓
+3. If still broken, send a model retry prompt via model router:
+   “Convert the following response into valid JSON only.”
+        ↓
+4. If retry fails, use regex to extract numeric scores and key sections.
+        ↓
+5. If all parsing fails, show a graceful fallback scorecard:
+   “Scorecard could not be fully structured, but here is the raw feedback.”
+```
+
+### Implementation Notes
+
+- Never expose raw Python errors in the UI.
+- Always show something useful to the user.
+- Log parse failures in the backend console for debugging.
+- Keep a default scorecard schema so the frontend never breaks.
+
+---
+
+## 16. Frontend UI Design
+
+### Design Goal
+
+The app should not look like a basic Gradio demo. It should feel like a polished AI practice arena.
+
+### Screens
+
+1. Landing screen
+2. Mode selection
+3. Startup / negotiation context form
+4. Persona selection
+5. Text or voice input selection
+6. Battle arena
+7. Scorecard screen
+8. Retry / new battle screen
+
+### Visual Direction
+
+```text
+Theme: Dark Battle Arena
+Background: near-black / navy
+Primary accent: red
+Secondary accent: gold
+Cards: dark glassmorphism
+Typography: bold headings, clean mono-style chat
+Animations: subtle glow, score reveal, pressure meter pulse
+```
+
+### UI Elements
+
+- Round counter
+- Pressure meter
+- Attack tag
+- Opponent card
+- Founder card
+- Voice recording button
+- Chat transcript
+- End battle button
+- Score bars
+- Weakest answer highlight
+- Improved answer card
+
+---
+
+## 17. Hugging Face Spaces Deployment Plan
+
+### Space Type
+
+```yaml
+---
+title: PitchFight AI
+emoji: ⚔️
+colorFrom: red
+colorTo: yellow
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+```
+
+### Core Environment Variables
+
+Set in HF Space Secrets and local `.env` (never commit real keys):
+
+```text
+APP_ENV=production
+MAX_ROUNDS=6
+
+NVIDIA_API_KEY=<hf-space-secret>
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
+
+OPENBMB_API_KEY=<hf-space-secret>
+OPENBMB_BASE_URL=
+MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
+MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+
+HF_TOKEN=<hf-space-secret>
+WHISPER_FALLBACK_ENABLED=true
+WHISPER_MODEL_SIZE=tiny
+```
+
+Do **not** expose keys in frontend code, README, or public repos.
+
+### Required `packages.txt`
+
+```text
+ffmpeg
+```
+
+### Important Security Rules
+
+- Never commit real API keys.
+- Never put keys in frontend JavaScript.
+- Use `.env` locally only for configuration.
+- Add `.env` to `.gitignore`.
+- Sponsor model API keys (NVIDIA, OpenBMB) are required for the premium demo path; they stay backend-only.
+
+---
+
+## 18. Final Deployment File Structure
+
+```text
+pitchfight-ai/
+│
+├── app.py
+├── requirements.txt
+├── packages.txt
+├── README.md
+├── .env.example
+├── .gitignore
+│
+├── core/
+│   ├── __init__.py
+│   ├── api_handlers.py
+│   ├── session_manager.py
+│   ├── persona_builder.py
+│   ├── attack_tags.py
+│   ├── model_router.py
+│   ├── nvidia_client.py
+│   ├── minicpm_client.py
+│   ├── vision_client.py
+│   ├── transcription_client.py
+│   ├── scoring_engine.py
+│   ├── feedback_generator.py
+│   ├── json_utils.py
+│   └── samples.py
+│
+├── config/
+│   ├── personas.json
+│   ├── attack_tags.json
+│   ├── pitch_rubric.json
+│   ├── deal_rubric.json
+│   └── sample_startups.json
+│
+├── frontend/
+│   ├── index.html
+│   ├── styles.css
+│   ├── script.js
+│   └── assets/
+│       ├── logo.svg
+│       └── icons/
+│
+├── docs/
+│   ├── DOCUMENTATION.md
+│   ├── PROMPTS.md
+│   ├── DEMO_NOTES.md
+│   └── FIELD_NOTES.md
+│
+└── tests/
+    ├── test_prompts.py
+    ├── test_attack_tags.py
+    └── test_json_parser.py
+```
+
+---
+
+## 19. File Responsibilities
+
+### `app.py`
+
+Main Gradio Server entry point.
+
+Responsibilities:
+
+- Create `gradio.Server`
+- Serve custom `frontend/index.html`
+- Serve static CSS/JS/assets
+- Expose backend APIs
+- Launch app
+
+### `core/session_manager.py`
+
+Stores active battle sessions.
+
+Responsibilities:
+
+- Create sessions
+- Store conversation history
+- Track rounds
+- Track persona and mode
+- Track attack tags
+- Return full conversation for scoring
+
+### `core/persona_builder.py`
+
+Builds persona prompts.
+
+Responsibilities:
+
+- Load persona config
+- Inject startup or negotiation context
+- Add difficulty rules
+- Add current attack tag
+- Return system prompt
+
+### `core/attack_tags.py`
+
+Controls structured pressure flow.
+
+Responsibilities:
+
+- Store attack tag taxonomy
+- Select next attack tag per persona
+- Avoid repeating the same attack tag too often
+- Increase pressure as rounds progress
+
+### `core/model_router.py`
+
+Backend-only model routing (Phase 2+).
+
+Responsibilities:
+
+- Text battle → NVIDIA Nemotron Omni by default; MiniCPM5-1B on failure
+- Voice input → Nemotron Omni primary; faster-whisper transcription fallback
+- OpenBMB omni mode → MiniCPM-o 4.5
+- Deck critique → MiniCPM-V 4.6 or Nemotron vision path
+- Expose active mode badge to frontend (`premium_nvidia`, `openbmb_omni`, `tiny_minicpm`, etc.)
+
+### `core/nvidia_client.py`
+
+Secure NVIDIA Nemotron Omni client (Phase 2+).
+
+Responsibilities:
+
+- Backend-only API calls via `NVIDIA_API_KEY`
+- Text, voice, multimodal judge responses
+- Scorecard and rewrite generation
+- Timeout / retry handling
+
+### `core/minicpm_client.py`
+
+OpenBMB MiniCPM backend client (Phase 2+).
+
+Responsibilities:
+
+- MiniCPM-o omni mode
+- MiniCPM5-1B tiny / fallback text generation
+
+### `core/transcription_client.py`
+
+Voice transcription fallback.
+
+Responsibilities:
+
+- Accept audio file
+- Run faster-whisper locally when Omni voice path fails
+- Return transcript for model router
+
+### `core/vision_client.py`
+
+Deck critique vision client (Phase 2+).
+
+Responsibilities:
+
+- Route slide images to MiniCPM-V 4.6 or Nemotron vision path
+
+### `core/scoring_engine.py`
+
+Generates scorecard.
+
+Responsibilities:
+
+- Build scoring prompt
+- Call model router (Nemotron default, MiniCPM5 fallback)
+- Parse JSON
+- Use fallback strategy if JSON breaks
+
+### `core/feedback_generator.py`
+
+Generates improved answers.
+
+Responsibilities:
+
+- Rewrite weakest answer
+- Generate improved pitch
+- Generate top 3 prep questions
+
+### `core/json_utils.py`
+
+Keeps frontend stable.
+
+Responsibilities:
+
+- Parse scorecard JSON
+- Repair malformed JSON
+- Extract fallback sections
+- Return default schema if needed
+
+### `frontend/index.html`
+
+Custom UI shell.
+
+Responsibilities:
+
+- Landing page
+- Mode selector
+- Form screens
+- Battle arena
+- Scorecard layout
+
+### `frontend/script.js`
+
+Frontend logic.
+
+Responsibilities:
+
+- Call `/api/*` endpoints via `fetch()` only — never model provider APIs
+- Manage UI state
+- Render messages and scorecards
+- Handle audio recording
+
+### `frontend/styles.css`
+
+Visual polish.
+
+Responsibilities:
+
+- Dark battle theme
+- Cards
+- Animations
+- Responsive layout
+- Score bars
+- Pressure meter
+
+---
+
+## 20. Development Phases
+
+> **Authoritative roadmap:** [`PHASE_WISE_PLAN.md`](PHASE_WISE_PLAN.md) (14 phases, sponsor-model strategy). The summary below aligns with that plan.
+
+This section describes the build order at a high level. The project can be built fast, but the documentation should not contradict itself by calling a full build a “one-day plan.”
+
+### Phase 1 — Project Skeleton
+
+Goal: create working HF Spaces-compatible Gradio Server app.
+
+Deliverables:
+
+- `app.py`
+- custom homepage
+- `requirements.txt`
+- `packages.txt`
+- README metadata
+
+Success check:
+
+```text
+python app.py
+```
+
+opens the custom UI.
+
+---
+
+### Phase 2 — Model Router + Secrets (see PHASE_WISE_PLAN.md)
+
+Goal: backend-only model routing with `DEFAULT_MODEL_MODE=premium_nvidia`.
+
+---
+
+### Phase 3 — Text Battle Engine
+
+Goal: get core pitch battle working.
+
+Deliverables:
+
+- session manager
+- persona builder
+- attack tag selector
+- `/start_session`
+- `/chat_round`
+
+Success check:
+
+```text
+User can start a pitch battle and get hard follow-up questions.
+```
+
+---
+
+### Phase 4 — Scorecard Engine
+
+Goal: turn chat into useful feedback.
+
+Deliverables:
+
+- scoring prompt
+- JSON parser
+- fallback parser
+- `/end_battle`
+- scorecard UI
+
+Success check:
+
+```text
+User ends battle and sees 6 scores, weakest answer, improved answer, and improved pitch.
+```
+
+---
+
+### Phase 5 — Custom UI Polish
+
+Goal: make it look like a product.
+
+Deliverables:
+
+- battle arena layout
+- round counter
+- pressure meter
+- persona cards
+- attack tag display
+- score animation
+- loading states
+
+Success check:
+
+```text
+The app visually feels different from default Gradio.
+```
+
+---
+
+### Phase 6 — Voice Pitch Mode
+
+Goal: Nemotron Omni primary voice path; faster-whisper transcription fallback only.
+
+Deliverables:
+
+- browser audio recorder
+- `/api/voice-pitch`
+- `transcription_client.py` (faster-whisper fallback)
+- transcript panel
+- text battle continuation from voice input
+
+Success check:
+
+```text
+User records a pitch and receives a hard first question via Nemotron (or whisper → text fallback).
+```
+
+---
+
+### Phase 7 — NVIDIA Nemotron Integration (primary)
+
+Goal: Nemotron Omni 30B-A3B as default premium judge (backend-only API).
+
+Deliverables:
+
+- `nvidia_client.py`
+- model router default `premium_nvidia`
+- MiniCPM5-1B fallback on failure
+
+Success check:
+
+```text
+Backend returns sharp judge questions and scorecards via Nemotron; app degrades to MiniCPM5 on failure.
+```
+
+---
+
+### Phase 8 — Deployment
+
+Goal: deploy to Hugging Face Spaces.
+
+Deliverables:
+
+- push repo
+- set non-secret config if needed
+- verify app runs publicly
+- test full flow
+
+Success check:
+
+```text
+HF Space link opens and completes one full battle.
+```
+
+---
+
+## 21. Minimum Viable Winning Version
+
+If time gets tight, ship this:
+
+- Pitch Battle only
+- Text input only
+- 3 personas
+- Attack tags
+- 6-round chat
+- NVIDIA Nemotron Omni via backend (MiniCPM5-1B fallback)
+- Scorecard
+- Improved answer
+- Custom UI
+- HF Spaces deployment
+
+Then add Voice Mode after deployment.
+
+---
+
+## 22. Full Winning Version
+
+Best final version:
+
+- Pitch Battle
+- Deal Battle
+- Local Voice Mode
+- 3 pitch personas
+- 2 negotiation personas
+- Attack tags
+- Scorecard
+- Improved answer
+- Retry weak question
+- Custom Gradio Server UI
+- HF Spaces deployment
+- Documentation
+- Field Notes
+- Public prompts and rubrics
+- NVIDIA Nemotron + OpenBMB MiniCPM sponsor-model stack
+
+---
+
+## 23. Badge / Prize Strategy
+
+| Target | How PitchFight AI Qualifies |
+|---|---|
+| Backyard AI | Built for student founders with a real high-pressure problem |
+| Best Demo | Voice + text pitch battle → scorecard in one polished flow |
+| Best Agent | Persona + memory + attack-tag planning + evaluation loop |
+| Off-Brand | Custom frontend using Gradio Server instead of default Gradio UI |
+| NVIDIA Nemotron Quest | Nemotron Omni as premium voice/multimodal judge |
+| OpenBMB Awards | MiniCPM-o, MiniCPM5-1B, MiniCPM-V integration |
+| Tiny Titan | MiniCPM5-1B Tiny Mode fallback |
+| Sharing is Caring | Publish prompts, rubrics, attack tags, sample scenarios |
+| Field Notes | Write short build post after deployment |
+| ~~Off the Grid~~ | **Not targeted** — sponsor APIs used intentionally for demo quality |
+
+---
+
+## 24. Environment and Safety
+
+Use this `.env.example`:
+
+```text
+APP_ENV=development
+MAX_ROUNDS=6
+
+NVIDIA_API_KEY=
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
+
+OPENBMB_API_KEY=
+OPENBMB_BASE_URL=
+MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
+MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+
+HF_TOKEN=
+WHISPER_FALLBACK_ENABLED=true
+WHISPER_MODEL_SIZE=tiny
+```
+
+Use this `.gitignore`:
+
+```text
+.env
+__pycache__/
+*.pyc
+.DS_Store
+node_modules/
+.gradio/
+models/
+*.gguf
+```
+
+Security rules:
+
+- Do not commit API keys.
+- Do not call model APIs from frontend JS — frontend uses `/api/*` only.
+- Store keys in `.env` locally and HF Space Secrets in deployment.
+- NVIDIA and OpenBMB sponsor APIs are the intended default inference path (backend-only).
+
+---
+
+## 25. Sample Demo Startup
+
+```json
+{
+  "name": "EventRadar AI",
+  "problem": "Students miss hackathons, tech events, and startup opportunities because discovery is scattered across WhatsApp groups, LinkedIn, Luma, college clubs, and random websites.",
+  "target_users": "College students, student founders, and early-stage builders.",
+  "solution": "AI-powered event discovery that ranks opportunities based on skills, goals, location, and deadline urgency.",
+  "why_ai": "The app does not just list events. It matches events to a student's profile and explains why each event is worth attending.",
+  "competitors": "Luma, LinkedIn Events, WhatsApp groups, college club pages.",
+  "traction": "Prototype built with scraped event data and ranking logic.",
+  "ask": "Hackathon prize and mentor feedback."
+}
+```
+
+---
+
+## 26. Demo Flow
+
+1. Open app.
+2. Click “Load Demo Startup”.
+3. Select “Hackathon Judge”.
+4. Choose “Text Battle” or “Voice Pitch”.
+5. AI asks:  
+   “Why does this need AI? A sorted event list with filters seems enough.”
+6. User gives a weak answer.
+7. AI selects an attack tag such as “Retention” and pushes back harder.
+8. End battle.
+9. Scorecard shows:
+   - Overall score
+   - 6 rubric scores
+   - Weakest answer
+   - Improved answer
+   - Improved 60-second pitch
+   - Top 3 prep questions
+
+Final spoken line:
+
+> **That is PitchFight AI — your first tough pitch should not be in front of a real judge.**
+
+---
+
+## 27. Final Implementation Checklist
+
+### Core
+
+- [ ] Custom Gradio Server app runs
+- [ ] Frontend loads from `frontend/index.html`
+- [ ] Frontend calls `/api/*` only (no direct model API calls)
+- [ ] Model router + Nemotron client wired (Phase 2+)
+- [ ] Session creation works
+- [ ] Persona prompt works
+- [ ] Attack tag selector works
+- [ ] Chat round works
+- [ ] Scorecard works
+- [ ] JSON parsing fallback works
+- [ ] Sample startup loads
+
+### Voice
+
+- [ ] Browser recorder works
+- [ ] Audio file reaches backend
+- [ ] faster-whisper transcribes locally
+- [ ] Transcript becomes usable context
+- [ ] AI asks voice-based first question
+
+### NVIDIA Nemotron (primary)
+
+- [ ] Backend-only Nemotron client uses HF Space Secrets / `.env`
+- [ ] MiniCPM5-1B fallback when Nemotron fails or keys missing
+- [ ] Model mode badge visible in UI
+
+### Deployment
+
+- [ ] HF Space created
+- [ ] README metadata added
+- [ ] `packages.txt` includes ffmpeg
+- [ ] App builds
+- [ ] Full flow tested publicly
+- [ ] No API keys exposed in frontend or public repo
+- [ ] Model router fallbacks tested when sponsor APIs fail
+
+---
+
+## 28. Final One-Line Description
+
+**PitchFight AI is a voice-and-text AI sparring arena where student founders practice tough startup pitches, get grilled by realistic AI judges under 32B parameters, and receive a scorecard that shows exactly how to answer better.**
+
+---
+
+## 29. Final Project Promise
+
+PitchFight AI is not trying to replace mentors or investors.
+
+It prepares student founders for them.
+
+> **The goal is simple: make the first hard question happen inside the app — not on stage.**
+
+---
+
+## 30. Reference Notes
+
+- Off-the-Grid is **not** targeted; sponsor-model APIs (NVIDIA, OpenBMB) power the default high-quality demo.
+- All models ≤32B; Gradio Server + custom HTML/CSS/JS frontend.
+- `core/model_router.py` selects premium_nvidia, openbmb_omni, tiny_minicpm, vision_deck, whisper_fallback.
+- API keys only in HF Space Secrets / backend `os.getenv`.
+- See `PHASE_WISE_PLAN.md` for the 14-phase implementation roadmap.

docs/FIELD_NOTES.md

@@ -0,0 +1,92 @@
+# PitchFight AI — Field Notes
+
+## Why This Exists
+
+Student founders often practice pitches alone or with friendly feedback. The first real pressure hits during judging, mentoring, investor calls, or sponsorship negotiations. PitchFight AI creates a safe but intense sparring arena before that moment.
+
+## Strategic Pivot (Phase 0)
+
+We moved from an **Off-the-Grid / local-first** strategy to a **high-demo sponsor-model** strategy:
+
+- **Not targeting** Off-the-Grid badge.
+- **Targeting** Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, Field Notes.
+- Still compliant: ≤32B models, Gradio, HF Spaces, no frontend API keys.
+
+## What Was Built
+
+### Phase 1 (Complete)
+
+- Hugging Face Spaces-ready Gradio Server skeleton
+- Custom battle arena frontend (HTML/CSS/JS)
+- In-memory session manager
+- Persona + attack-tag routing
+- Mock scoring and feedback (placeholder for real models)
+- Config files for personas, rubric, samples
+
+### Planned (Phases 2–14)
+
+- Model router + NVIDIA / OpenBMB clients
+- Real Pitch Battle + Deal Battle engines
+- Voice pitch mode (Nemotron primary, whisper fallback)
+- Pitch deck critique (MiniCPM-V)
+- Retry weakest question + downloadable report
+- UI polish + public HF Space deployment
+
+## What the Models Will Do
+
+| Model | Job |
+|---|---|
+| Nemotron Omni | Premium judge, voice, scoring, rewrites |
+| MiniCPM-o | OpenBMB multimodal mode |
+| MiniCPM5-1B | Tiny/fallback text |
+| MiniCPM-V 4.6 | Slide critique |
+| faster-whisper | Backup transcription |
+
+## What Worked
+
+- Clean separation: frontend → Gradio API → model router → clients
+- Attack-tag driven pressure design
+- Runnable Phase 1 skeleton for fast iteration
+- Clear phase-wise plan for hackathon execution
+
+## What Will Be Improved
+
+- Replace mock APIs with Nemotron + MiniCPM routing (Phase 2–5)
+- Voice mode as headline demo feature (Phase 7)
+- Deal Battle + deck critique (Phases 8–10)
+- Product polish and public deployment (Phases 12–14)
+
+## Build Log
+
+### Phase 2 — Model Router + Secrets Setup (2026-06-08)
+
+**What shipped:**
+- `core/nvidia_client.py` — backend-only NVIDIA Nemotron client using OpenAI-compatible SDK
+- `core/model_router.py` — central routing layer (premium_nvidia live; other modes return clean stubs)
+- `core/minicpm_client.py` — health_check stub (Phase 9 placeholder)
+- `core/vision_client.py` — health_check stub (Phase 10 placeholder)
+- `core/transcription_client.py` — health_check stub (Phase 7 placeholder)
+- `scripts/test_nvidia_client.py` — isolated connectivity test (exits 0/1, no key exposure)
+- `GET /api/model-health` — config status endpoint, keys never exposed
+- `requirements.txt` updated: added `openai>=1.0.0`, `httpx`, `requests`
+
+**What worked:**
+- NVIDIA API key read from `NVIDIA_API_KEY` env var only — no hardcoding, no key leak
+- `health_check()` correctly reports configured/not-configured without printing key
+- `generate_nemotron_response()` returns clean judge question on first real test
+- `get_model_health()` returns correct provider status for all four providers
+- Error handling catches timeout, connection, and status errors cleanly
+
+**What surprised us:**
+- `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` is a **reasoning model**: it writes an internal chain-of-thought before the final answer. When `max_tokens` is too small (< ~400 for opponent mode), all tokens are consumed by the reasoning trace and `message.content` is `None`.
+- The fix: increase `max_tokens` defaults (opponent: 500, scorecard: 2000, rewrite: 800) and add a `reasoning_content` fallback for edge cases.
+- The final answer in `message.content` is sharp, in-character, and correctly short — the reasoning trace stays internal.
+
+**What the model returned (live test):**
+> "How does your AI differentiate between similar events and avoid false positives in ranking?"
+
+**What we'd do differently:**
+- Test with the actual model before setting token defaults — reasoning models have different budget dynamics than completion models.
+
+**What's next:**
+- Phase 3: Wire `model_router.generate_opponent_response()` into `handle_start_session` and `handle_chat_round` in `core/api_handlers.py` — replacing hardcoded mock followups with live Nemotron responses.

docs/MODELS_FINAL.md

@@ -0,0 +1,434 @@
+# PitchFight AI — Final Model Strategy
+
+## High-Demo Sponsor-Model Stack Under 32B Parameters
+
+---
+
+## 1. Final Model Philosophy
+
+PitchFight AI prioritizes:
+
+- **Best demonstrative experience** — the app must feel like a real sparring arena, not a chatbot wrapper.
+- **Voice-first pitch practice** — founders pitch out loud; the judge responds with pressure, not generic advice.
+- **High-quality AI judge behavior** — persona-locked opponents, attack tags, memory, and sharp follow-ups.
+- **Sponsor-model alignment** — NVIDIA Nemotron Omni and OpenBMB MiniCPM models used intentionally and visibly.
+- **Strong fallback reliability** — if a premium endpoint fails, the app degrades gracefully instead of breaking the demo.
+- **Models under 32B parameters** — every reasoning model in the stack complies with the Build Small Hackathon cap.
+
+The project is **not** targeting the **Off-the-Grid** badge. This is intentional — Off-the-Grid is not part of this build.
+
+The app **does** follow the required hackathon rules:
+
+- **≤32B models** for all core reasoning
+- **Gradio** + **Hugging Face Spaces** hosting
+- **Demo-first** execution with a custom non-default UI
+
+**Target badges/prizes:** Backyard AI, Best Demo, Best Agent, Off-Brand, NVIDIA Nemotron Quest, OpenBMB Awards, Sharing is Caring, and Field Notes.
+
+Cloud/sponsor model APIs are **allowed and expected** for this build when called **backend-only** with keys in HF Space Secrets. They are not forbidden — they are the default path to demo quality.
+
+---
+
+## 2. Final Default Model Stack
+
+| Layer | Final Model | Default? | Purpose |
+|---|---|---:|---|
+| Premium reasoning + voice/multimodal judge | NVIDIA Nemotron 3 Nano Omni 30B-A3B | Yes | Main voice/text judge, pitch battle, deal battle, scorecard, voice critique |
+| OpenBMB omni mode | MiniCPM-o 4.5 | Secondary | OpenBMB-aligned omni mode for voice/text/multimodal pitch interaction |
+| Tiny fallback | MiniCPM5-1B | Fallback | Fast text battle, scorecard fallback, Tiny Mode |
+| Vision/deck critique | MiniCPM-V 4.6 | Feature mode | Pitch deck screenshot critique and visual pitch feedback |
+| Audio fallback | faster-whisper / Whisper Tiny or Base | Fallback | Audio transcription if direct audio handling is unstable |
+| Optional multilingual | Cohere Aya or suitable small multilingual model | Optional | Hindi/Kannada/regional pitch practice if added |
+| Optional visuals | FLUX / Black Forest Labs model | Optional assets only | Persona art or visual assets, not core reasoning |
+
+---
+
+## 3. Primary Model — NVIDIA Nemotron 3 Nano Omni 30B-A3B
+
+> **Deep dive:** How Omni processes raw audio, paralinguistic signals, hesitation detection, and PitchFight voice paths A/B — see [`NEMOTRON_OMNI_AUDIO.md`](NEMOTRON_OMNI_AUDIO.md).
+
+### Role
+
+Primary premium model for the strongest demo.
+
+### Use cases
+
+- Voice pitch understanding
+- AI opponent responses
+- Pitch Battle
+- Deal Battle
+- Multimodal pitch judging
+- Scorecard generation
+- Weakest answer rewrite
+- Improved pitch generation
+- Voice-specific feedback
+- Optional pitch deck + spoken pitch critique
+
+### Why
+
+- Strong sponsor alignment (NVIDIA Nemotron Quest)
+- Multimodal / omni capability
+- Under 32B total parameter rule
+- Best fit for high-quality voice demo
+- Targets NVIDIA Nemotron Quest
+
+### Implementation
+
+- Backend-only API call.
+- API key stored in HF Space Secrets.
+- Frontend never calls NVIDIA directly.
+- Model call goes through `core/nvidia_client.py` and `core/model_router.py`.
+
+### Environment variables
+
+```text
+NVIDIA_API_KEY=
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
+```
+
+### Suggested settings
+
+| Task | Temperature | Max Tokens |
+|---|---:|---:|
+| Opponent response | 0.7 | 250 |
+| Scorecard | 0.2 | 1200 |
+| Rewrite | 0.45 | 500 |
+
+---
+
+## 4. OpenBMB Mode — MiniCPM-o 4.5
+
+### Role
+
+OpenBMB-aligned advanced omni model.
+
+### Use cases
+
+- Alternative voice judge mode
+- Speech/text pitch interaction
+- OpenBMB sponsor route
+- Model comparison mode
+- Optional multimodal interaction
+
+### Why
+
+- 9B model, under 32B
+- Strong OpenBMB alignment
+- Supports omnimodal interaction
+- Useful for OpenBMB Awards
+- Smaller than Nemotron
+
+### Implementation
+
+- Backend-only API call or supported official endpoint.
+- Keep separate from NVIDIA path.
+- Can be exposed in UI as **“OpenBMB Omni Mode”**.
+
+### Environment variables
+
+```text
+OPENBMB_API_KEY=
+OPENBMB_BASE_URL=
+MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
+```
+
+---
+
+## 5. Tiny / Fallback Mode — MiniCPM5-1B
+
+### Role
+
+Reliable small fallback model.
+
+### Use cases
+
+- Text Pitch Battle fallback
+- Deal Battle fallback
+- Scorecard fallback
+- Tiny Mode
+- Low-latency text mode
+- Tiny Titan angle if shipped well
+
+### Why
+
+- Very small
+- OpenBMB-aligned
+- Good backup if premium endpoints are slow
+- Keeps app usable during API failures
+
+### Implementation
+
+- Use through backend model router.
+- Can be local or hosted depending on final deployment.
+- If using API, clearly do not claim Off-the-Grid.
+- If local, can be mentioned as optional local fallback.
+
+### Environment variables
+
+```text
+MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
+MINICPM_TEXT_BACKEND=api_or_local
+```
+
+---
+
+## 6. Vision Mode — MiniCPM-V 4.6
+
+### Role
+
+Pitch deck screenshot critique.
+
+### Use cases
+
+- Upload slide screenshot
+- Extract visible claims
+- Critique clarity
+- Critique problem/solution/market/ask
+- Generate judge questions from slide
+
+### Why
+
+- OpenBMB-aligned
+- Small visual model
+- Strong demo feature
+- Adds multimodal value beyond chat
+
+### Implementation
+
+- Add `/deck_critique` endpoint.
+- Frontend image upload.
+- Backend routes image to MiniCPM-V or NVIDIA Omni.
+- Show slide critique card.
+
+### Environment variables
+
+```text
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+```
+
+---
+
+## 7. Audio Fallback — faster-whisper
+
+### Role
+
+Backup transcription.
+
+### Use cases
+
+- Convert audio to transcript if direct omni audio fails
+- Debug voice input
+- Allow browser-recorded audio to become text reliably
+
+### Why
+
+- Reliable
+- Simple
+- Helps prevent voice demo failure
+
+### Implementation
+
+- **Not** the main judge.
+- Only audio-to-text fallback.
+- Transcript then goes into selected reasoning model.
+
+### Environment variables
+
+```text
+WHISPER_FALLBACK_ENABLED=true
+WHISPER_MODEL_SIZE=tiny
+```
+
+---
+
+## 8. Model Router
+
+Routing logic for `core/model_router.py`:
+
+### Text Pitch Battle
+
+```text
+startup context + persona + attack tag
+  → NVIDIA Nemotron by default
+  → MiniCPM5-1B fallback if NVIDIA fails
+```
+
+### Voice Pitch
+
+```text
+audio
+  → NVIDIA Nemotron Omni primary
+  → if fails: faster-whisper transcription
+  → MiniCPM5-1B or Nemotron text path
+```
+
+### Deal Battle
+
+```text
+negotiation context
+  → NVIDIA Nemotron by default
+  → MiniCPM5-1B fallback
+```
+
+### Scorecard
+
+```text
+conversation history
+  → NVIDIA Nemotron by default
+  → MiniCPM5-1B fallback
+  → json_utils parser + fallback_scorecard()
+```
+
+### Deck Critique
+
+```text
+image
+  → MiniCPM-V 4.6 or NVIDIA Omni
+  → slide critique + judge questions
+```
+
+### OpenBMB Mode
+
+```text
+user-selected
+  → MiniCPM-o 4.5
+```
+
+### Tiny Mode
+
+```text
+user-selected or automatic fallback
+  → MiniCPM5-1B
+```
+
+---
+
+## 9. Model-to-File Mapping
+
+| File | Responsibility | Phase 2 Status |
+|---|---|---|
+| `core/model_router.py` | Routes tasks to NVIDIA, MiniCPM-o, MiniCPM5, MiniCPM-V, or Whisper fallback | **Created** — premium_nvidia live; other modes stub |
+| `core/nvidia_client.py` | Calls NVIDIA Nemotron Omni backend-only | **Created** — live, tested |
+| `core/minicpm_client.py` | Calls MiniCPM-o and MiniCPM5 paths | **Stub** — health_check only (Phase 9) |
+| `core/vision_client.py` | Handles MiniCPM-V / deck critique model calls | **Stub** — health_check only (Phase 10) |
+| `core/transcription_client.py` | Handles faster-whisper fallback transcription | **Stub** — health_check only (Phase 7) |
+| `core/session_manager.py` | Stores selected model mode and conversation history | Existing — unchanged |
+| `core/persona_builder.py` | Builds prompt before model call | Existing — unchanged |
+| `core/attack_tags.py` | Selects pressure direction before model call | Existing — unchanged |
+| `core/scoring_engine.py` | Builds scorecard prompt and calls model_router | Existing — still mock (Phase 5) |
+
+> **Reasoning model token note:** `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` writes an internal chain-of-thought before producing `message.content`. Confirmed defaults: opponent=500, scorecard=2000, rewrite=800 tokens.
+| `core/json_utils.py` | Repairs/parses model-generated scorecards |
+
+---
+
+## 10. Environment Variables
+
+Final environment block:
+
+```text
+APP_ENV=development
+MAX_ROUNDS=6
+
+DEFAULT_MODEL_MODE=premium_nvidia
+
+NVIDIA_API_KEY=
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
+
+OPENBMB_API_KEY=
+OPENBMB_BASE_URL=
+MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
+MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+
+HF_TOKEN=
+
+WHISPER_FALLBACK_ENABLED=true
+WHISPER_MODEL_SIZE=tiny
+
+ENABLE_DECK_CRITIQUE=true
+ENABLE_DEAL_BATTLE=true
+ENABLE_VOICE_MODE=true
+```
+
+**Security rules:**
+
+- API keys must be **backend-only**.
+- Use **HF Space Secrets** in production.
+- Never expose keys in frontend JS.
+- Do not commit `.env`.
+
+---
+
+## 11. Requirements Strategy
+
+### Skeleton (always)
+
+```text
+gradio
+fastapi
+uvicorn
+pydantic
+python-dotenv
+numpy
+```
+
+### API/model clients
+
+```text
+openai
+requests
+httpx
+```
+
+### Voice fallback
+
+```text
+faster-whisper
+```
+
+### Audio/system
+
+```text
+packages.txt includes ffmpeg
+```
+
+### Optional image handling
+
+```text
+pillow
+```
+
+**Note:** Do not add heavy local inference dependencies unless needed. This build prioritizes **API-backed sponsor models** for demo quality. Local inference (e.g. llama-cpp-python) is optional for Tiny Mode fallback only — not the default path.
+
+---
+
+## 12. Model Architecture Diagram
+
+```mermaid
+flowchart TD
+    A[User Text Pitch] --> B[Custom Gradio UI]
+    C[User Voice Pitch] --> B
+    D[Pitch Deck Screenshot] --> B
+
+    B --> E[Gradio Server Backend]
+    E --> F[Model Router]
+
+    F --> G[NVIDIA Nemotron Omni\nPremium Judge Mode]
+    F --> H[MiniCPM-o 4.5\nOpenBMB Omni Mode]
+    F --> I[MiniCPM5-1B\nTiny/Fallback Mode]
+    F --> J[MiniCPM-V 4.6\nDeck Critique Mode]
+    F --> K[faster-whisper\nAudio Fallback]
+
+    G --> L[Opponent Response + Scorecard]
+    H --> L
+    I --> L
+    J --> M[Slide Critique + Judge Questions]
+    K --> N[Transcript]
+    N --> F
+
+    L --> O[Battle Arena UI]
+    M --> O
+```

docs/NEMOTRON_OMNI_AUDIO.md

@@ -0,0 +1,294 @@
+# NVIDIA Nemotron 3 Nano Omni — Audio & Voice Architecture
+
+Technical reference for how **NVIDIA Nemotron 3 Nano Omni 30B-A3B** processes pitch audio in PitchFight AI, what it can infer about hesitation and confidence, and how the app should wire voice mode.
+
+> **PitchFight context:** Nemotron Omni is the **primary premium judge** (backend-only API). Raw audio goes to the model on the primary path. **faster-whisper** is transcription fallback only — not the main judge. Frontend never calls NVIDIA directly; audio flows through `/api/voice-pitch`.
+
+See also: [`MODELS_FINAL.md`](MODELS_FINAL.md) · [`BACKEND_API.md`](BACKEND_API.md) · [`PHASE_WISE_PLAN.md`](PHASE_WISE_PLAN.md)
+
+---
+
+## 1. Model Identity
+
+| Field | Value |
+|---|---|
+| **Model** | NVIDIA Nemotron 3 Nano Omni 30B-A3B |
+| **Env var** | `NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` |
+| **Parameter cap** | ~30B — complies with Build Small ≤32B rule |
+| **Access** | Backend-only via `NVIDIA_API_KEY` + `NVIDIA_BASE_URL` |
+| **Role in PitchFight** | Primary voice/text/multimodal judge, scorecard, rewrites |
+
+---
+
+## 2. How the Model Works With Audio
+
+### Unified encoder–projector–decoder design
+
+NeMoTron Nano Omni uses a **unified multimodal architecture**:
+
+- **Language backbone:** Nemotron 3 Nano 30B-A3B (reasoning)
+- **Vision encoder:** C-RADIOv4-H
+- **Audio encoder:** Parakeet-TDT-0.6B-v2
+
+Modality-specific encoders connect into the LLM backbone through **lightweight projectors**. Audio and text share the same reasoning loop inside the backbone.
+
+### Exact pipeline when an audio file hits the model
+
+```text
+Your WAV / audio file (raw bytes)
+        ↓
+Parakeet-TDT-0.6B-v2 (dedicated audio encoder)
+        ↓ converts audio into audio tokens
+Lightweight projector (aligns audio tokens to LLM embedding space)
+        ↓
+Nemotron 30B-A3B backbone (reasoning happens here)
+        ↓
+Structured text output (transcript, observations, judge question, etc.)
+```
+
+### What this is *not*
+
+This is **fundamentally different** from Whisper → LLM:
+
+| Approach | Flow |
+|---|---|
+| **Whisper → LLM** | Audio → text transcript → text-only reasoning |
+| **Nemotron Omni (primary path)** | Audio → audio tokens → projected embeddings → unified reasoning |
+
+On the Nemotron primary path, the model does **not** need to transcribe to plain text first before reasoning. Audio signals are preserved as tokens that flow into the backbone.
+
+### Paralinguistic coverage
+
+Parakeet provides strong ASR. NVIDIA extends the audio surface with **Granary** and **Music Flamingo** extensions, broadening coverage beyond bare transcription to include:
+
+- Paralinguistic signals (tone, pace, stress, hesitation sounds)
+- Music and ambient sound understanding
+
+**Paralinguistic** = signals beyond literal words — how something is said, not only what is said. This is what makes the model competitive on voice benchmarks and useful for media understanding, not just dictation.
+
+---
+
+## 3. Quick Answers (FAQ)
+
+| Question | Answer |
+|---|---|
+| Does the raw audio file go to Nemotron? | **Yes** — Parakeet processes native audio input. |
+| Does it get transcribed to text first? | **No** on the primary Omni path — audio tokens flow directly into reasoning. |
+| Does it use embeddings? | **Yes** — audio tokens are projected into the LLM embedding space. |
+| Can it detect hesitation? | **Yes** — linguistic hesitation and filler words reliably. |
+| Can it detect confidence from voice tone? | **Partially** — paralinguistic inference, not clinical prosody analysis. |
+| Is this strong enough for a pitch trainer? | **Yes** — linguistic hesitation is the most actionable signal for founders. |
+| How do you make it accurate? | **Prompt explicitly** for delivery observations alongside content. |
+
+---
+
+## 4. Hesitation & Confidence Detection
+
+### Partially yes — with important caveats
+
+#### What it can detect reliably
+
+The Parakeet encoder (with Granary / Music Flamingo extensions) processes **paralinguistic features**. When preserved as audio tokens in the backbone, the LLM can reason about:
+
+| Signal | Example |
+|---|---|
+| Filler words | "um", "uh", "like", "you know" |
+| Long pauses | Mid-sentence gaps before a key claim |
+| Trailing off | Weak endings on important statements |
+| Rushed speech | Compressed delivery on uncertain phrases |
+| Repetition / self-correction | Restarts, hedging, reformulations |
+
+For pitch training, **linguistic hesitation is often the most useful signal**:
+
+> *"Um… I think… maybe the market is… around 10 million?"*  
+> vs  
+> *"The addressable market is $10M based on X."*
+
+The model can flag the first pattern when prompted correctly.
+
+#### What it cannot detect reliably
+
+Pure acoustic / physiological confidence signals require dedicated prosody tools (e.g. Praat, specialized emotion models), not a general-purpose multimodal LLM:
+
+- Heart rate change
+- Micro-tremors in voice
+- Subtle pitch drops indicating clinical-level uncertainty
+
+**Do not claim** heart-rate or micro-tremor detection in PitchFight UI or demo script.
+
+#### Honest positioning
+
+NeMoTron can detect **linguistic hesitation** (words and sounds of hesitation) and make **reasonable inferences** about apparent confidence from speech patterns. It cannot do **clinical-grade prosody analysis**. For a student pitch trainer, that is the right tradeoff.
+
+---
+
+## 5. Voice Scorecard Metrics (Grounded in Architecture)
+
+Only score dimensions the model can plausibly observe:
+
+| Metric | How Nemotron detects it | Reliability |
+|---|---|---|
+| Filler word count | Direct from audio tokens + transcript | **High** |
+| Pause before key claims | Temporal gap in audio | **Medium–High** |
+| Self-corrections | Restarts in transcript / audio pattern | **High** |
+| Trailing off on weak claims | Audio token patterns | **Medium** |
+| Speaking pace (rushed vs calm) | Token density over time | **Medium** |
+| Confidence on specific claims | Inference from above signals | **Medium** |
+
+When on **Whisper fallback**, mark voice-derived metrics as unavailable or transcript-only.
+
+---
+
+## 6. PitchFight AI Voice Architecture
+
+### Path A — Nemotron direct (primary, when API available)
+
+```text
+Browser records audio
+        ↓
+POST /api/voice-pitch (backend only)
+        ↓
+NVIDIA Nemotron Omni
+        ↓
+Parakeet encoder processes raw audio
+        ↓
+Paralinguistic + linguistic signals preserved in backbone
+        ↓
+Single API response includes:
+  - transcript
+  - delivery_observations (hesitation / pace / fillers)
+  - detected_startup_context
+  - opening judge question
+        ↓
+Pitch Battle continues (voice or text)
+```
+
+**UI badge:** `⚡ Voice Analysis Active` (or similar) when Path A is active.
+
+### Path B — Whisper fallback (when Nemotron audio path fails)
+
+```text
+Browser records audio
+        ↓
+POST /api/voice-pitch
+        ↓
+faster-whisper local transcription
+        ↓
+Clean transcript text only (no paralinguistic tokens)
+        ↓
+Nemotron or MiniCPM5-1B text reasoning
+        ↓
+Judge question (no delivery observations)
+        ↓
+Scorecard notes: "Voice delivery metrics unavailable in fallback mode"
+```
+
+**UI badge:** `📝 Text Mode` (transcript-only fallback).
+
+Path A is the **demo differentiator**. Path B keeps the app working when audio API fails, keys are missing, or latency/errors trigger fallback.
+
+### Security
+
+- Audio upload hits **backend only** — never send `NVIDIA_API_KEY` to the browser.
+- Keys live in `.env` locally and **HF Space Secrets** in deployment.
+
+---
+
+## 7. Recommended Voice Prompt (Hesitation / Delivery)
+
+When sending audio to Nemotron for `/api/voice-pitch`, include instructions like:
+
+```text
+Listen to this pitch audio carefully.
+
+Beyond the words spoken, note:
+- Any filler words (um, uh, like, you know, sort of)
+- Any long pauses before answering a key claim
+- Any statements that trail off or sound uncertain
+- Any rushing through parts they seem unsure about
+- Any self-corrections or restarts
+
+After understanding the pitch, include a section called
+DELIVERY OBSERVATIONS with specific timestamps or quotes
+where hesitation or low confidence was audible.
+
+Extract startup context fields if possible.
+Then ask your first hard judge question in character.
+Return structured JSON when requested.
+```
+
+Anchoring the model to **delivery observations** makes paralinguistic reporting explicit instead of hoping it infers them silently.
+
+### Suggested structured response fields (Phase 7+)
+
+```json
+{
+  "transcript": "...",
+  "delivery_observations": [
+    {
+      "type": "filler_words",
+      "quote_or_timestamp": "0:12 — 'um, I think maybe...'",
+      "note": "Hedging before market size claim"
+    }
+  ],
+  "detected_startup_context": { },
+  "opening_question": "..."
+}
+```
+
+Exact schema should match `core/api_handlers.py` when voice mode is implemented.
+
+---
+
+## 8. Comparison: Nemotron Omni vs faster-whisper
+
+| | Nemotron Omni (Path A) | faster-whisper (Path B) |
+|---|---|---|
+| **Input** | Raw audio | Raw audio |
+| **Output** | Transcript + reasoning + delivery signals | Transcript text only |
+| **Hesitation / pace** | Paralinguistic tokens in backbone | Not available |
+| **Judge question** | Same call or follow-up text call | Requires separate text model call |
+| **Role in PitchFight** | Primary voice judge | Transcription fallback only |
+| **Runs** | NVIDIA API (backend) | Local on Space / dev machine |
+
+---
+
+## 9. Implementation Notes (Future Phases)
+
+Planned wiring (no app logic in this doc — reference only):
+
+| Module | Responsibility |
+|---|---|
+| `core/nvidia_client.py` | Send audio + prompt to Nemotron API; parse structured response |
+| `core/model_router.py` | Choose `premium_nvidia` vs `whisper_fallback` |
+| `core/transcription_client.py` | faster-whisper when Omni audio fails |
+| `core/api_handlers.py` | `handle_voice_pitch()` orchestration |
+| `frontend/script.js` | Upload audio to `/api/voice-pitch` only |
+
+### Fallback triggers (suggested)
+
+- NVIDIA API timeout or 5xx
+- Missing `NVIDIA_API_KEY`
+- Audio format unsupported by API
+- Explicit `WHISPER_FALLBACK_ENABLED=true` override for debugging
+
+### Demo talking points
+
+1. **Raw audio goes to Nemotron** — not transcribe-then-reason on the premium path.
+2. **Delivery observations** — fillers, pauses, trailing off — are first-class signals.
+3. **Honest limits** — we score linguistic hesitation, not biometrics.
+4. **Graceful fallback** — whisper keeps voice mode alive without breaking the demo.
+
+---
+
+## 10. References
+
+- NVIDIA Nemotron 3 Nano Omni model card and integrate API docs (NVIDIA NIM / integrate.api.nvidia.com)
+- Build Small Hackathon: ≤32B models, Gradio/HF Spaces, demo-first
+- PitchFight model stack: [`MODELS_FINAL.md`](MODELS_FINAL.md)
+
+---
+
+## 11. Bottom Line
+
+Nemotron Omni is the right primary voice model for PitchFight because it processes **raw audio through a dedicated encoder into a shared reasoning backbone**, preserving paralinguistic cues that matter for pitch coaching. Pair it with an explicit **delivery observations** prompt, honest scorecard metrics, and a **whisper fallback** that degrades visibly — not silently — when the premium audio path is unavailable.

docs/PHASE_WISE_PLAN.md

@@ -0,0 +1,478 @@
+# PitchFight AI — Phase-Wise Implementation Plan
+
+## Full Sponsor-Model Build Plan for Voice, Text, Deal Battle, Scorecards, and Demo Polish
+
+PitchFight AI is a voice-and-text AI sparring arena for student founders. The project prioritizes the strongest possible demo experience using small models under 32B, including NVIDIA Nemotron Omni for premium voice/multimodal judge behavior, OpenBMB MiniCPM models for sponsor-aligned modes, a custom Gradio Server frontend, persona-based pitch battles, deal negotiation battles, and rubric-based scorecards.
+
+> **Strategy note:** This version does **not** claim the Off-the-Grid badge because the default high-quality build may use sponsor/model APIs. This is intentional. The project instead targets **Backyard AI**, **Best Demo**, **Best Agent**, **Off-Brand**, **NVIDIA Nemotron Quest**, **OpenBMB Awards**, **Sharing is Caring**, and **Field Notes**.
+
+---
+
+## 1. Final Build Goal
+
+The complete final app includes:
+
+- Custom Gradio Server app
+- Custom HTML/CSS/JS frontend
+- Pitch Battle mode
+- Deal Battle mode
+- Voice Pitch mode
+- Text Pitch mode
+- AI opponent personas
+- Attack-tag routing
+- Session memory
+- NVIDIA Nemotron Omni integration
+- MiniCPM-o / MiniCPM fallback modes
+- MiniCPM-V pitch deck critique mode
+- Scorecard engine
+- Weakest answer rewrite
+- Improved 60-second pitch
+- Retry weakest question
+- HF Spaces deployment
+- Documentation and demo notes
+
+**Focus:** demo strength, model quality, and sponsor-model alignment — **not** Off-the-Grid.
+
+All models stay **≤32B parameters**. The app is built on **Gradio**, hosted as a **Hugging Face Space**, uses a **custom non-default UI**, and keeps **all API keys in backend/HF Space Secrets** only (never in the frontend).
+
+---
+
+## 2. Master Build Order
+
+| Phase | Name |
+|---|---|
+| **Phase 0** | Strategy Reset + Documentation Alignment |
+| **Phase 1** | Project Skeleton Verification |
+| **Phase 2** | Model Router + Secrets Setup |
+| **Phase 3** | NVIDIA Nemotron Omni Integration |
+| **Phase 4** | Pitch Battle Engine |
+| **Phase 5** | Scorecard + Feedback Engine |
+| **Phase 6** | Custom Frontend Integration |
+| **Phase 7** | Voice Pitch Mode |
+| **Phase 8** | Deal Battle Mode |
+| **Phase 9** | MiniCPM / OpenBMB Modes |
+| **Phase 10** | Pitch Deck Critique Mode |
+| **Phase 11** | Retry + Report Enhancements |
+| **Phase 12** | UI Polish + Demo Flow |
+| **Phase 13** | Hugging Face Spaces Deployment |
+| **Phase 14** | Final Testing + Submission Readiness |
+
+---
+
+## 3. Phase 0 — Strategy Reset + Documentation Alignment
+
+**Goal:** Ensure all repository docs reflect the high-demo sponsor-model strategy (historical local-first/off-grid wording removed).
+
+**Tasks:**
+
+- Remove wording that says the default build is Off-the-Grid.
+- Keep a note that Off-the-Grid is **not** targeted.
+- Update model strategy to include **NVIDIA Nemotron Omni** as the primary premium model.
+- Add **MiniCPM-o** as OpenBMB advanced mode.
+- Add **MiniCPM5-1B** as Tiny/Fallback mode.
+- Add **MiniCPM-V 4.6** as pitch deck critique mode.
+- Keep **faster-whisper** as backup transcription fallback.
+- Update `README.md`, `docs/DOCUMENTATION.md`, `docs/PROMPTS.md`, `docs/DEMO_NOTES.md`, `docs/FIELD_NOTES.md`, and `docs/MODELS_FINAL.md` accordingly.
+
+**Success check:** All docs agree that the project is under 32B, Gradio/HF Spaces based, and high-demo sponsor-model focused.
+
+---
+
+## 4. Phase 1 — Project Skeleton Verification
+
+**Goal:** Verify that the existing Gradio Server + custom frontend skeleton works.
+
+**Tasks:**
+
+- Check `app.py` exists.
+- Check `frontend/index.html`, `styles.css`, `script.js` exist.
+- Check `core/` modules exist.
+- Check `config/` files exist.
+- Run `python app.py`.
+- Confirm custom UI opens.
+- Confirm mock battle works.
+- Confirm mock scorecard appears.
+
+**Files:**
+
+- `app.py`
+- `frontend/*`
+- `core/*`
+- `config/*`
+- `docs/*`
+
+**Success check:** Custom PitchFight AI UI opens and mock demo flow runs.
+
+**Current status:** ✅ Complete (Phase 1 skeleton in place with mock APIs).
+
+**API layer:** Clean product endpoints live under `/api/...` (see [`BACKEND_API.md`](BACKEND_API.md)). Gradio internal routes in Swagger are framework runtime routes, not PitchFight product APIs.
+
+---
+
+## 5. Phase 2 — Model Router + Secrets Setup
+
+**Goal:** Create a clean backend-only model routing layer.
+
+**Tasks:**
+
+- Create or update `core/model_router.py`.
+- Create or update `core/nvidia_client.py`.
+- Create or update `core/minicpm_client.py`.
+- Create or update `core/vision_client.py`.
+- Create or update `core/transcription_client.py`.
+- Ensure frontend never calls model APIs.
+- Add env variables to `.env.example`.
+- Read keys only from `os.getenv` (`.env` locally, HF Space Secrets in deployment).
+- Frontend calls `/api/*` only — never model provider APIs.
+- Add graceful fallback if a model call fails.
+
+**Environment variables:**
+
+```text
+NVIDIA_API_KEY=
+NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
+NVIDIA_OMNI_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
+
+OPENBMB_API_KEY=
+OPENBMB_BASE_URL=
+MINICPM_OMNI_MODEL=openbmb/MiniCPM-o-4_5
+MINICPM_TEXT_MODEL=openbmb/MiniCPM5-1B
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+
+HF_TOKEN=
+WHISPER_FALLBACK_ENABLED=true
+MAX_ROUNDS=6
+APP_ENV=development
+```
+
+**Success check:** Backend can select a model path:
+
+- `premium_nvidia`
+- `openbmb_omni`
+- `tiny_minicpm`
+- `vision_deck`
+- `whisper_fallback`
+
+**Current status:** ✅ Complete (2026-06-08). `core/nvidia_client.py` and `core/model_router.py` created. NVIDIA connectivity tested — live response confirmed. Stub clients created for MiniCPM, vision, and transcription. `GET /api/model-health` added.
+
+**Key discovery:** `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` is a reasoning model. It uses tokens for an internal chain-of-thought before writing `message.content`. Token defaults: opponent=500, scorecard=2000, rewrite=800. A `reasoning_content` fallback is in place for edge cases.
+
+---
+
+## 6. Phase 3 — NVIDIA Nemotron Omni Integration
+
+**Goal:** Make NVIDIA Nemotron Omni the primary premium reasoning and voice/multimodal judge model.
+
+**Tasks:**
+
+- Implement secure backend call using `NVIDIA_API_KEY`.
+- Add function `generate_nemotron_response(messages, mode)`.
+- Add timeout handling.
+- Add retry handling.
+- Add fallback to MiniCPM mode if NVIDIA fails.
+- Test text-only judge prompt first.
+- Test scoring prompt second.
+- Test voice/multimodal input after text works.
+
+**Use cases:**
+
+- AI opponent response
+- Voice pitch critique
+- Deal battle counterpart
+- Scorecard generation
+- Weakest answer rewrite
+- Optional pitch deck + spoken explanation critique
+
+**Success check:** Backend receives a startup context and Nemotron returns a sharp judge question.
+
+---
+
+## 7. Phase 4 — Pitch Battle Engine
+
+**Goal:** Make Pitch Battle real.
+
+**Tasks:**
+
+- Connect `/start_session` to `model_router`.
+- Connect `/chat_round` to `model_router`.
+- Use `persona_builder.py`.
+- Use `attack_tags.py`.
+- Store history in `session_manager.py`.
+- Rotate attack tags.
+- Return `attack_tag`, `pressure_level`, `round`, `ai_message`.
+- Support 3 personas:
+  - Skeptical VC
+  - Technical Judge
+  - Hackathon Judge
+
+**Success check:** User enters EventRadar AI, selects Hackathon Judge, and receives a sharp AI challenge.
+
+---
+
+## 8. Phase 5 — Scorecard + Feedback Engine
+
+**Goal:** Generate real scorecards.
+
+**Tasks:**
+
+- Build scoring prompt from conversation history.
+- Use NVIDIA Nemotron as default scorer.
+- Use MiniCPM fallback if needed.
+- Parse scorecard JSON safely.
+- Implement JSON fallback pipeline.
+- Generate:
+  - overall score
+  - 6 pitch dimensions
+  - best answer
+  - weakest answer
+  - improved answer
+  - improved pitch
+  - top 3 prep questions
+
+**Files:**
+
+- `core/scoring_engine.py`
+- `core/feedback_generator.py`
+- `core/json_utils.py`
+- `app.py`
+- `frontend/script.js`
+
+**Success check:** End Battle produces structured scorecard with user quotes and useful rewrites.
+
+---
+
+## 9. Phase 6 — Custom Frontend Integration
+
+**Goal:** Connect UI fully to backend APIs.
+
+**Tasks:**
+
+- Connect Gradio JS Client.
+- Load demo startup.
+- Start session.
+- Render AI question.
+- Render user messages.
+- Render AI follow-ups.
+- Render attack tag.
+- Render pressure meter.
+- Render scorecard.
+- Show model mode badge:
+  - Premium Nemotron
+  - OpenBMB Omni
+  - Tiny MiniCPM
+- Handle errors and loading states.
+
+**Success check:** User can complete full Pitch Battle from UI.
+
+---
+
+## 10. Phase 7 — Voice Pitch Mode
+
+**Goal:** Make voice mode a major demo feature.
+
+**Primary path:**
+
+```text
+Browser records audio
+  → backend sends audio/transcript to NVIDIA Nemotron Omni
+  → AI extracts pitch understanding
+  → AI asks first hard question
+  → user continues by voice or text
+```
+
+**Fallback path:**
+
+```text
+Browser records audio
+  → faster-whisper transcribes locally
+  → transcript goes to selected text model
+  → battle starts
+```
+
+**Tasks:**
+
+- Add browser audio recorder.
+- Add `/voice_pitch` endpoint.
+- Add audio upload handling.
+- Add transcript/interpretation panel.
+- Add user editable transcript.
+- Add voice-specific metrics:
+  - Structure
+  - Conciseness
+  - Confidence Signals
+  - Directness
+- Continue battle from voice input.
+
+**Success check:** User records a pitch and receives a hard first question.
+
+---
+
+## 11. Phase 8 — Deal Battle Mode
+
+**Goal:** Add negotiation practice.
+
+**Scenarios:**
+
+- Startup Sponsorship Ask
+- Internship Salary Negotiation
+- Freelance Client Pricing
+- Equity Negotiation
+
+**Personas:**
+
+- Tough Sponsor
+- Strict HR Recruiter
+- Budget-Conscious Client
+- Hard-Negotiating Investor
+
+**Tasks:**
+
+- Add Deal Battle mode to UI.
+- Add negotiation context form.
+- Add deal personas.
+- Add deal attack tags.
+- Add deal rubric.
+- Route deal battle to `model_router`.
+- Generate negotiation-specific scorecard.
+
+**Success check:** User can negotiate and receive a deal-specific scorecard.
+
+---
+
+## 12. Phase 9 — MiniCPM / OpenBMB Modes
+
+**Goal:** Add OpenBMB sponsor-aligned models and fallback modes.
+
+**Models:**
+
+- **MiniCPM-o 4.5** — OpenBMB Omni Mode
+- **MiniCPM5-1B** — Tiny Mode / fallback
+- **MiniCPM-V 4.6** — vision mode
+
+**Tasks:**
+
+- Add model selector or backend mode switch.
+- Add OpenBMB Omni mode.
+- Add Tiny MiniCPM mode.
+- Add fallback if NVIDIA errors.
+- Add docs explaining model use cases.
+
+**Success check:** App can run at least one OpenBMB mode and one fallback mode.
+
+---
+
+## 13. Phase 10 — Pitch Deck Critique Mode
+
+**Goal:** Add image/slide critique.
+
+**Primary model:** MiniCPM-V 4.6 or NVIDIA Omni.
+
+**Tasks:**
+
+- Add image upload.
+- Add `/deck_critique` endpoint.
+- Extract slide claims.
+- Critique clarity, problem, solution, market, ask.
+- Generate 3 judge questions based on the slide.
+
+**Success check:** User uploads a pitch slide screenshot and receives useful critique.
+
+---
+
+## 14. Phase 11 — Retry + Report Enhancements
+
+**Goal:** Make it feel product-ready.
+
+**Tasks:**
+
+- Add Retry Weakest Question.
+- Store weakest AI question.
+- Compare original vs retried answer.
+- Generate downloadable markdown report.
+- Add full session summary.
+- Add “Start New Battle”.
+
+**Success check:** User can retry the weakest objection and get improvement guidance.
+
+---
+
+## 15. Phase 12 — UI Polish + Demo Flow
+
+**Goal:** Make it visually memorable.
+
+**Tasks:**
+
+- Improve landing hero.
+- Add model mode badges.
+- Add premium voice mode card.
+- Add deck critique card.
+- Add battle arena split layout.
+- Add score animations.
+- Add voice recording animation.
+- Add mobile responsiveness.
+- Add error banners.
+- Add loading states.
+
+**Design:** Dark battle arena, red pressure accents, gold score accents, glass cards, custom typography.
+
+**Success check:** The app looks like a custom product, not default Gradio.
+
+---
+
+## 16. Phase 13 — Hugging Face Spaces Deployment
+
+**Goal:** Deploy publicly.
+
+**Tasks:**
+
+- Add README metadata.
+- Add required secrets in HF Space Settings.
+- Confirm app builds.
+- Confirm no keys are exposed.
+- Test all modes publicly.
+- Add screenshots to README.
+- Add final Space link.
+
+**Success check:** Public HF Space completes:
+
+- Text Pitch Battle
+- Voice Pitch Battle
+- Deal Battle
+- Scorecard
+- Deck critique (if built)
+
+---
+
+## 17. Phase 14 — Final Testing + Submission Readiness
+
+**Tasks:**
+
+- Test every endpoint.
+- Test every UI button.
+- Test failure fallback.
+- Test missing API keys.
+- Test slow responses.
+- Test mobile layout.
+- Update README.
+- Update docs.
+- Prepare demo flow.
+- Prepare field notes.
+- Prepare social post separately.
+
+**Badges/prizes to mention:**
+
+- Backyard AI
+- Best Demo
+- Best Agent
+- Off-Brand
+- NVIDIA Nemotron Quest
+- OpenBMB Awards
+- Sharing is Caring
+- Field Notes
+- Tiny Titan (if Tiny Mode works)
+
+---
+
+## Final One-Line Pitch
+
+**PitchFight AI is a voice-and-text AI sparring arena where student founders practice tough startup pitches, get grilled by realistic AI judges under 32B parameters, and receive a scorecard that shows exactly how to answer better.**

docs/PROMPTS.md

@@ -0,0 +1,155 @@
+# PitchFight AI — Prompt Templates
+
+## Model Routing (Backend Only)
+
+All prompts are sent through `core/model_router.py`. Default scorer and opponent: **NVIDIA Nemotron Omni**. Fallback: **MiniCPM5-1B**. Voice primary path: Nemotron Omni audio; fallback: **faster-whisper** → text model.
+
+> API keys never appear in prompts or frontend code. Keys are read from `os.getenv` on the backend only.
+
+---
+
+## Opponent System Prompt Template
+
+Used by Nemotron Omni (primary) and MiniCPM fallback.
+
+```text
+You are {persona_label}, a tough pitch opponent in PitchFight AI.
+Difficulty: {difficulty}
+Current attack tag: {attack_tag}
+Round: {round_number} of {max_rounds}
+
+Startup: {startup_name}
+Problem: {problem}
+Solution: {solution}
+Why AI: {why_ai}
+Target users: {target_users}
+Competitors: {competitors}
+Traction: {traction}
+
+Conversation so far:
+{history}
+
+{persona_focus}
+
+Behavior rules:
+- Ask one sharp question at a time.
+- Keep responses under 4 sentences.
+- Reference the founder's previous answer when pushing back.
+- Do not give advice during the battle.
+- Do not compliment the founder.
+- Attack vague, generic, or unsubstantiated claims.
+- Raise difficulty after strong answers.
+- Stay in character at all times.
+- Be firm but not abusive.
+- Frame your question around the current attack tag: {attack_tag}.
+
+Return only your next question as plain text (no JSON).
+```
+
+---
+
+## Scoring Prompt Template
+
+Default model: **NVIDIA Nemotron Omni**. Fallback: MiniCPM5-1B + `json_utils.safe_json_parse`.
+
+```text
+You are a pitch battle evaluator. Score the founder's performance using the rubric below.
+Return valid JSON only — no markdown fences, no commentary.
+
+Rubric weights:
+- clarity: 15
+- problem_understanding: 20
+- market_awareness: 15
+- differentiation: 20
+- business_model: 15
+- objection_handling: 15
+
+Startup context:
+{startup_json}
+
+Conversation:
+{history_json}
+
+Return exactly this JSON shape:
+{
+  "overall": <0-100>,
+  "scores": {
+    "clarity": {"score": <0-100>, "reason": "...", "quote": "..."},
+    "problem_understanding": {"score": <0-100>, "reason": "...", "quote": "..."},
+    "market_awareness": {"score": <0-100>, "reason": "...", "quote": "..."},
+    "differentiation": {"score": <0-100>, "reason": "...", "quote": "..."},
+    "business_model": {"score": <0-100>, "reason": "...", "quote": "..."},
+    "objection_handling": {"score": <0-100>, "reason": "...", "quote": "..."}
+  },
+  "best_answer": "...",
+  "weakest_answer": "...",
+  "improved_answer": "...",
+  "improved_pitch": "...",
+  "top_3_questions": ["...", "...", "..."]
+}
+```
+
+---
+
+## Voice Pitch Extraction Prompt (Nemotron Omni)
+
+```text
+You heard a student founder's spoken pitch. Extract structured startup context and identify the weakest claim.
+
+Return JSON:
+{
+  "name": "...",
+  "problem": "...",
+  "target_users": "...",
+  "solution": "...",
+  "why_ai": "...",
+  "competitors": "...",
+  "traction": "...",
+  "ask": "...",
+  "voice_metrics": {
+    "structure": <0-100>,
+    "conciseness": <0-100>,
+    "confidence_signals": <0-100>,
+    "directness": <0-100>
+  },
+  "first_hard_question": "..."
+}
+```
+
+---
+
+## Pitch Deck Critique Prompt (MiniCPM-V / Nemotron Vision)
+
+```text
+You are a hackathon judge reviewing one pitch slide image.
+
+Critique: clarity, problem, solution, market, ask.
+Return JSON:
+{
+  "slide_summary": "...",
+  "strengths": ["..."],
+  "weaknesses": ["..."],
+  "judge_questions": ["...", "...", "..."]
+}
+```
+
+---
+
+## Persona Behavior Rules
+
+| Persona | Focus |
+|---|---|
+| Skeptical VC | Market size, moat, retention, revenue, defensibility |
+| Technical Judge | AI justification, architecture, scalability, data quality |
+| Hackathon Judge | Novelty, demo clarity, MVP strength, backyard fit |
+
+## Attack Tag Lists
+
+### Skeptical VC
+Market Size, Moat, Retention, Revenue Logic, First 100 Users, Why Now, Competition, Defensibility
+
+### Technical Judge
+AI Justification, Architecture, Scalability, Latency, Data Quality, Failure Mode, Simpler Alternative, Technical Feasibility
+
+### Hackathon Judge
+Novelty, Demo Clarity, MVP Strength, User Pain, AI Load-Bearing, Backyard Fit, Practical Impact, Judging Memorability

docs/TASK_TRACKER.md

@@ -0,0 +1,105 @@
+# PitchFight AI — Task Tracker
+
+## Current Phase
+
+Phase 2 complete: Model Router + Secrets Setup (2026-06-08)
+
+## Next Phase
+
+Phase 3: Wire model_router into battle flow (handle_start_session + handle_chat_round)
+
+---
+
+## Phase Status Table
+
+| Phase | Name | Status | Notes |
+|---|---|---|---|
+| 0 | Strategy Reset + Documentation Alignment | Complete | Off-the-Grid removed; sponsor-model strategy locked |
+| 1 | Project Skeleton Verification | Complete | Mock app runs; custom frontend live; all /api/* endpoints return responses |
+| 2 | Model Router + Secrets Setup | **Complete** (2026-06-08) | nvidia_client, model_router, stub clients created; NVIDIA tested live |
+| 3 | NVIDIA Nemotron Omni Integration | Pending | Depends on Phase 2 |
+| 4 | Pitch Battle Engine | Pending | Replace mock followups with real Nemotron responses |
+| 5 | Scorecard + Feedback Engine | Pending | Real scoring via Nemotron; json_utils already ready |
+| 6 | Custom Frontend Integration | Pending | Model mode badge; error/loading polish |
+| 7 | Voice Pitch Mode | Pending | Browser audio → Nemotron Omni; fallback to whisper |
+| 8 | Deal Battle Mode | Pending | Negotiation scenarios + deal personas |
+| 9 | MiniCPM / OpenBMB Modes | Pending | MiniCPM-o, MiniCPM5-1B, fallback routing |
+| 10 | Pitch Deck Critique Mode | Pending | MiniCPM-V 4.6 image upload + slide critique |
+| 11 | Retry + Report Enhancements | Pending | Retry weakest question; downloadable markdown report |
+| 12 | UI Polish + Demo Flow | Pending | Animations, model badges, mobile, dark arena look |
+| 13 | Hugging Face Spaces Deployment | Pending | HF Space Secrets, public test, screenshots |
+| 14 | Final Testing + Submission Readiness | Pending | All endpoints, all modes, all failure paths |
+
+---
+
+## Immediate Next Tasks (Phase 3)
+
+1. In `core/api_handlers.py`: import `model_router` and `persona_builder`
+2. In `handle_start_session`: build system prompt via `persona_builder.build_persona_prompt()`, call `model_router.generate_opponent_response()`, use mock opening as fallback if `ok=False`
+3. In `handle_chat_round`: build message list from session history, call `model_router.generate_opponent_response()`, use mock followup as fallback if `ok=False`
+4. Run full battle flow end-to-end: load sample → start session → 2 chat rounds → end battle
+5. Confirm Nemotron response is sharp, persona-locked, and references attack tag
+6. Update docs after confirming end-to-end works
+
+**Do not touch scoring, voice, deal battle, or deck critique in Phase 3.**
+
+---
+
+## Phase 2 Completed Tasks
+
+- [x] `.env.example` verified — all variables present and correct
+- [x] `core/nvidia_client.py` created
+  - [x] Reads keys from `os.getenv` only — no hardcoded values
+  - [x] `generate_nemotron_response(messages, mode, temperature, max_tokens, timeout)` implemented
+  - [x] Timeout handling (30s default)
+  - [x] Returns string on success; raises `RuntimeError` with clean message on failure
+  - [x] `reasoning_content` fallback for reasoning model edge cases
+  - [x] No API key or URL hardcoded anywhere
+- [x] `core/model_router.py` created
+  - [x] Routes `premium_nvidia` → nvidia_client (live)
+  - [x] Stub/placeholder routes for `openbmb_omni`, `tiny_minicpm`, `vision_deck`, `whisper_fallback`
+  - [x] Graceful fallback if NVIDIA fails (`ok=False`, fallback message returned, no crash)
+  - [x] `get_model_health()` — all providers, no key exposure
+- [x] `core/minicpm_client.py` stub created (health_check only)
+- [x] `core/vision_client.py` stub created (health_check only)
+- [x] `core/transcription_client.py` stub created (health_check only)
+- [x] `scripts/test_nvidia_client.py` — isolated test, exits 0 on success / 1 on failure
+- [x] Isolated NVIDIA test: **PASSED** — live Nemotron response confirmed
+- [x] `GET /api/model-health` added to `app.py`
+- [x] `requirements.txt` updated: `openai>=1.0.0`, `httpx`, `requests` added
+- [x] Mock followup lists remain in `api_handlers.py` — not removed
+- [x] `docs/PHASE_WISE_PLAN.md` Phase 2 marked Complete
+- [x] `docs/FIELD_NOTES.md` updated with Phase 2 build log
+- [x] `docs/BACKEND_API.md` `/api/model-health` added
+- [x] `docs/MODELS_FINAL.md` model-to-file mapping updated with Phase 2 status
+
+---
+
+## Phase 1 Completed Tasks (for reference)
+
+- [x] `app.py` — Gradio Server with `/api/*` REST routes and `@app.api` wrappers
+- [x] `frontend/index.html`, `styles.css`, `script.js` — custom battle arena UI
+- [x] `core/session_manager.py` — in-memory session store
+- [x] `core/persona_builder.py` — system prompt builder per persona
+- [x] `core/attack_tags.py` — tag taxonomy + round-based selector
+- [x] `core/scoring_engine.py` — mock scorecard with real session quotes
+- [x] `core/feedback_generator.py` — mock rewrite templates
+- [x] `core/json_utils.py` — JSON extraction, safe parse, fallback scorecard
+- [x] `core/samples.py` — EventRadar AI sample startup
+- [x] `core/local_text_model.py` — Phase 1 stub
+- [x] `core/voice_transcriber.py` — Phase 1 stub
+- [x] `config/personas.json`, `attack_tags.json`, `pitch_rubric.json`, `sample_startups.json`
+- [x] `docs/BACKEND_API.md`, `DOCUMENTATION.md`, `FIELD_NOTES.md`, `DEMO_NOTES.md`, `MODELS_FINAL.md`, `PHASE_WISE_PLAN.md`, `PROMPTS.md`
+- [x] `.env.example` — all required variables present
+
+---
+
+## Risks Before Phase 2
+
+| Risk | Mitigation |
+|---|---|
+| NVIDIA API key not yet provisioned | Get key from NVIDIA developer portal; add to `.env` before Phase 2 testing |
+| Nemotron endpoint may need special headers or model format | Test isolated before wiring into session flow |
+| `openai` Python SDK compatibility with NVIDIA base URL | NVIDIA uses OpenAI-compatible API; use `openai.OpenAI(base_url=..., api_key=...)` |
+| Session manager is in-memory; process restart loses sessions | Acceptable for hackathon; note as known limitation |
+| Mock fallback strings (MOCK_FOLLOWUPS) must stay in api_handlers.py | Do not delete until real model routing is confirmed stable |

frontend/index.html

@@ -0,0 +1,155 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>PitchFight AI</title>
+  <link rel="icon" href="/frontend/assets/logo.svg" type="image/svg+xml" />
+  <link rel="stylesheet" href="/frontend/styles.css" />
+</head>
+<body>
+  <div class="bg-glow"></div>
+
+  <div id="error-banner" class="error-banner" hidden role="alert"></div>
+
+  <main id="app" class="app">
+    <!-- Landing -->
+    <section id="screen-landing" class="screen active">
+      <header class="hero">
+        <img src="/frontend/assets/logo.svg" alt="PitchFight AI logo" class="logo" />
+        <h1>PitchFight AI</h1>
+        <p class="tagline">Your first tough pitch should not be in front of a real judge.</p>
+        <p class="subtitle">A small-model pressure simulator for student founders.</p>
+      </header>
+      <div class="hero-actions">
+        <button id="btn-load-sample" class="btn btn-secondary">Load Demo Startup</button>
+        <button id="btn-go-setup" class="btn btn-primary">Start Pitch Battle</button>
+      </div>
+    </section>
+
+    <!-- Setup -->
+    <section id="screen-setup" class="screen">
+      <div class="panel glass">
+        <div class="panel-header">
+          <h2>Startup Context</h2>
+          <button id="btn-back-landing" class="btn btn-ghost">Back</button>
+        </div>
+        <form id="startup-form" class="startup-form">
+          <label>Name<input name="name" type="text" placeholder="EventRadar AI" required /></label>
+          <label>Problem<textarea name="problem" rows="2" required></textarea></label>
+          <label>Target Users<input name="target_users" type="text" required /></label>
+          <label>Solution<textarea name="solution" rows="2" required></textarea></label>
+          <label>Why AI<textarea name="why_ai" rows="2" required></textarea></label>
+          <label>Competitors<input name="competitors" type="text" required /></label>
+          <label>Traction<input name="traction" type="text" required /></label>
+          <label>Ask<input name="ask" type="text" required /></label>
+        </form>
+      </div>
+
+      <div class="panel glass">
+        <h2>Choose Your Opponent</h2>
+        <div class="persona-grid">
+          <button class="persona-card" data-persona="skeptical_vc">
+            <span class="persona-icon">💼</span>
+            <h3>Skeptical VC</h3>
+            <p>Market, moat, revenue, defensibility</p>
+          </button>
+          <button class="persona-card" data-persona="technical_judge">
+            <span class="persona-icon">🛠️</span>
+            <h3>Technical Judge</h3>
+            <p>AI necessity, architecture, feasibility</p>
+          </button>
+          <button class="persona-card selected" data-persona="hackathon_judge">
+            <span class="persona-icon">🏆</span>
+            <h3>Hackathon Judge</h3>
+            <p>Novelty, demo clarity, MVP strength</p>
+          </button>
+        </div>
+        <button id="btn-start-battle" class="btn btn-primary btn-wide">Enter the Arena</button>
+      </div>
+    </section>
+
+    <!-- Battle -->
+    <section id="screen-battle" class="screen">
+      <div class="battle-layout">
+        <aside class="battle-meta glass">
+          <h2>Battle Arena</h2>
+          <div class="meta-item"><span>Round</span><strong id="round-counter">1</strong></div>
+          <div class="meta-item"><span>Pressure</span><strong id="pressure-level" class="pressure-high">High</strong></div>
+          <div class="meta-item"><span>Phase</span><strong id="battle-phase" hidden>explore</strong></div>
+          <div class="meta-item"><span>Attack Tag</span><strong id="attack-tag">—</strong></div>
+          <button id="btn-end-battle" class="btn btn-danger btn-wide">End Battle</button>
+          <button id="btn-back-scorecard" class="btn btn-ghost btn-wide" hidden>Back to Scorecard</button>
+        </aside>
+
+        <div class="battle-chat glass">
+          <div id="chat-window" class="chat-window" aria-live="polite"></div>
+          <form id="chat-form" class="chat-input-row">
+            <textarea id="user-input" rows="2" placeholder="Defend your startup under pressure..."></textarea>
+            <button id="btn-send" type="submit" class="btn btn-primary">Send</button>
+          </form>
+          <p id="battle-status" class="status-text" hidden></p>
+        </div>
+      </div>
+    </section>
+
+    <!-- Scorecard -->
+    <section id="screen-scorecard" class="screen">
+      <div class="panel glass scorecard-panel">
+        <header class="scorecard-header">
+          <div class="scorecard-header-left">
+            <h2>Battle Scorecard</h2>
+            <button id="btn-view-conversation" class="btn btn-ghost btn-sm">View Conversation</button>
+          </div>
+          <div class="overall-score">
+            <span>Overall</span>
+            <strong id="overall-score">0</strong>
+            <span id="overall-label" hidden style="font-size:0.85rem;color:var(--gold);display:block;margin-top:0.2rem"></span>
+          </div>
+          <p id="scorecard-source-badge" hidden style="font-size:0.8rem;opacity:0.7;margin:0"></p>
+        </header>
+
+        <div id="score-bars" class="score-bars"></div>
+
+        <p id="signals-summary" class="signals-summary" hidden></p>
+
+        <div class="feedback-grid">
+          <article class="feedback-card highlight">
+            <h3>Improved Answer</h3>
+            <p id="improved-answer"></p>
+          </article>
+          <article class="feedback-card highlight">
+            <h3>Improved Pitch</h3>
+            <p id="improved-pitch"></p>
+          </article>
+          <article class="feedback-card">
+            <h3>Best Answer</h3>
+            <p id="best-answer"></p>
+          </article>
+          <article class="feedback-card">
+            <h3>Weakest Answer</h3>
+            <p id="weakest-answer"></p>
+          </article>
+        </div>
+
+        <div class="prep-questions">
+          <h3>Top 3 Prep Questions</h3>
+          <ol id="top-questions"></ol>
+        </div>
+
+        <div class="scorecard-actions">
+          <button id="btn-reset" class="btn btn-secondary">New Battle</button>
+          <button id="btn-back-setup" class="btn btn-primary">Edit Startup</button>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <div id="loading-overlay" class="loading-overlay" hidden>
+    <div class="spinner"></div>
+    <p>Loading...</p>
+  </div>
+
+  <script type="module" src="/frontend/script.js"></script>
+</body>
+</html>

frontend/script.js

@@ -0,0 +1,376 @@
+const state = {
+  sessionId: null,
+  persona: "hackathon_judge",
+  round: 1,
+};
+
+const screens = {
+  landing: document.getElementById("screen-landing"),
+  setup: document.getElementById("screen-setup"),
+  battle: document.getElementById("screen-battle"),
+  scorecard: document.getElementById("screen-scorecard"),
+};
+
+const startupForm = document.getElementById("startup-form");
+const chatWindow = document.getElementById("chat-window");
+const userInput = document.getElementById("user-input");
+const loadingOverlay = document.getElementById("loading-overlay");
+const loadingText = loadingOverlay?.querySelector("p");
+const battleStatus = document.getElementById("battle-status");
+const errorBanner = document.getElementById("error-banner");
+
+function showScreen(name) {
+  Object.entries(screens).forEach(([key, el]) => {
+    el.classList.toggle("active", key === name);
+  });
+}
+
+function setGlobalLoading(isLoading, message = "Loading...") {
+  if (loadingText) loadingText.textContent = message;
+  loadingOverlay.hidden = !isLoading;
+}
+
+function showErrorBanner(message) {
+  errorBanner.textContent = message;
+  errorBanner.hidden = false;
+}
+
+function hideErrorBanner() {
+  errorBanner.hidden = true;
+  errorBanner.textContent = "";
+}
+
+function getStartupPayload() {
+  const data = new FormData(startupForm);
+  return Object.fromEntries(data.entries());
+}
+
+function fillStartupForm(startup) {
+  Object.entries(startup).forEach(([key, value]) => {
+    const field = startupForm.elements.namedItem(key);
+    if (field) field.value = value ?? "";
+  });
+}
+
+function appendMessage(role, text, meta = "") {
+  const bubble = document.createElement("div");
+  bubble.className = `message ${role}`;
+  bubble.innerHTML = meta
+    ? `<span class="message-meta">${meta}</span><p>${escapeHtml(text)}</p>`
+    : `<p>${escapeHtml(text)}</p>`;
+  chatWindow.appendChild(bubble);
+  chatWindow.scrollTop = chatWindow.scrollHeight;
+}
+
+function escapeHtml(text) {
+  return String(text)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function updateBattleMeta(data) {
+  document.getElementById("round-counter").textContent = data.round ?? state.round;
+  const pressureEl = document.getElementById("pressure-level");
+  pressureEl.textContent = data.pressure_level ?? "High";
+  pressureEl.className = `pressure-${(data.pressure_level ?? "high").toLowerCase()}`;
+  document.getElementById("attack-tag").textContent = data.attack_tag ?? "—";
+  state.round = data.round ?? state.round;
+
+  const phaseEl = document.getElementById("battle-phase");
+  if (phaseEl && data.battle_phase) {
+    phaseEl.textContent = data.battle_phase;
+    phaseEl.hidden = false;
+  }
+}
+
+async function apiPost(path, body = undefined) {
+  console.log(`API POST ${path}`, body ?? {});
+  const options = { method: "POST", headers: {} };
+
+  if (body !== undefined) {
+    options.headers["Content-Type"] = "application/json";
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(path, options);
+  const data = await response.json().catch(() => ({}));
+
+  if (!response.ok) {
+    const detail = data.detail || data.error || response.statusText;
+    throw new Error(`${path} failed: ${detail}`);
+  }
+
+  console.log(`API POST ${path} OK`, data);
+  return data;
+}
+
+export async function loadSample() {
+  try {
+    setGlobalLoading(true, "Loading demo startup...");
+    const data = await apiPost("/api/load-sample");
+    fillStartupForm(data.startup);
+    showScreen("setup");
+    hideErrorBanner();
+  } catch (error) {
+    console.error(error);
+    showErrorBanner("Failed to load demo startup. Check backend logs.");
+  } finally {
+    setGlobalLoading(false);
+  }
+}
+
+export async function startSession() {
+  try {
+    setGlobalLoading(true, "Starting pitch battle...");
+    battleStatus.hidden = true;
+    chatWindow.innerHTML = "";
+
+    const payload = {
+      mode: "pitch_battle",
+      startup: getStartupPayload(),
+      persona: state.persona,
+      difficulty: "high",
+      input_mode: "text",
+      model_mode: "premium_nvidia",
+    };
+
+    const data = await apiPost("/api/start-session", payload);
+
+    if (data.error) {
+      showErrorBanner(data.error);
+      return;
+    }
+
+    state.sessionId = data.session_id;
+    state.round = data.round ?? 1;
+    userInput.disabled = false;
+    const submitBtn = document.getElementById("chat-form").querySelector("button[type=submit]");
+    if (submitBtn) submitBtn.disabled = false;
+    updateBattleMeta(data);
+    const startBadge = data.model_ok ? "⚡ Premium Nemotron" : "Mock";
+    appendMessage("ai", data.ai_message, `${data.attack_tag} · Round ${data.round} · ${startBadge}`);
+    showScreen("battle");
+    hideErrorBanner();
+  } catch (error) {
+    console.error(error);
+    showErrorBanner("Failed to start battle. Check backend logs.");
+  } finally {
+    setGlobalLoading(false);
+  }
+}
+
+export async function sendMessage() {
+  const message = userInput.value.trim();
+  if (!message || !state.sessionId) return;
+
+  try {
+    setGlobalLoading(true, "Sending answer...");
+    userInput.value = "";
+    appendMessage("user", message);
+
+    const data = await apiPost("/api/chat-round", {
+      session_id: state.sessionId,
+      user_message: message,
+    });
+
+    if (data.error) {
+      battleStatus.hidden = false;
+      battleStatus.textContent = data.ai_message || data.error;
+      return;
+    }
+
+    updateBattleMeta(data);
+    const chatBadge = data.model_ok ? "⚡ Premium Nemotron" : "Mock";
+    appendMessage("ai", data.ai_message, `${data.attack_tag} · Round ${data.round} · ${chatBadge}`);
+
+    if (data.soft_round_limit_reached) {
+      battleStatus.hidden = false;
+      battleStatus.textContent = data.completion_message
+        ?? "You have enough material for a scorecard. End Battle when ready.";
+      battleStatus.style.color = "var(--gold)";
+    }
+  } catch (error) {
+    console.error(error);
+    battleStatus.hidden = false;
+    battleStatus.textContent = "Message failed. Try again.";
+  } finally {
+    setGlobalLoading(false);
+  }
+}
+
+export async function endBattle() {
+  if (!state.sessionId) return;
+
+  try {
+    setGlobalLoading(true, "Generating scorecard...");
+    const data = await apiPost("/api/end-battle", {
+      session_id: state.sessionId,
+    });
+
+    if (data.error) {
+      showErrorBanner(data.error);
+      return;
+    }
+
+    renderScorecard(data);
+    showScreen("scorecard");
+    hideErrorBanner();
+  } catch (error) {
+    console.error(error);
+    showErrorBanner("Failed to generate scorecard. Check backend logs.");
+  } finally {
+    setGlobalLoading(false);
+  }
+}
+
+export async function resetBattle() {
+  if (state.sessionId) {
+    try {
+      await apiPost("/api/reset-session", { session_id: state.sessionId });
+    } catch (error) {
+      console.error(error);
+    }
+  }
+
+  state.sessionId = null;
+  state.round = 1;
+  chatWindow.innerHTML = "";
+  userInput.value = "";
+  showScreen("landing");
+}
+
+function renderScorecard(data) {
+  const overall = data.overall ?? 0;
+  document.getElementById("overall-score").textContent = overall;
+
+  const overallLabelEl = document.getElementById("overall-label");
+  if (overallLabelEl) {
+    overallLabelEl.textContent = data.overall_label ?? "";
+    overallLabelEl.hidden = !data.overall_label;
+  }
+
+  const sourceBadgeEl = document.getElementById("scorecard-source-badge");
+  if (sourceBadgeEl) {
+    const src = data.scorecard_source ?? "";
+    sourceBadgeEl.textContent =
+      src === "hybrid_claims_nemotron" ? "⚡ Claim-based score + Premium Nemotron coaching" :
+      src === "hybrid_claims_local" ? "Claim-based local scorecard" :
+      src === "nemotron" ? "⚡ Scored by Premium Nemotron" :
+      src === "nemotron_repaired" ? "⚡ Scored by Premium Nemotron (repaired)" :
+      src === "session_fallback" ? "Session-based scorecard (model unavailable)" :
+      "Mock fallback scorecard";
+    sourceBadgeEl.hidden = false;
+  }
+
+  const bars = document.getElementById("score-bars");
+  bars.innerHTML = "";
+  const scores = data.scores ?? {};
+
+  Object.entries(scores).forEach(([key, value]) => {
+    const row = document.createElement("div");
+    row.className = "score-row";
+    const dimLabel = key.replaceAll("_", " ");
+    const scoreLabel = value.label ? `<span class="score-label">${escapeHtml(value.label)}</span>` : "";
+    row.innerHTML = `
+      <div class="score-row-head">
+        <span>${dimLabel}${scoreLabel}</span>
+        <strong>${value.score}</strong>
+      </div>
+      <div class="bar-track"><div class="bar-fill" style="width:${value.score}%"></div></div>
+      <p class="score-reason">${escapeHtml(value.reason ?? "")}</p>
+    `;
+    bars.appendChild(row);
+  });
+
+  // Concrete signals summary
+  const sigEl = document.getElementById("signals-summary");
+  if (sigEl) {
+    const css = data.concrete_signals_summary ?? {};
+    const allSigs = [
+      ...(css.numbers ?? []),
+      ...(css.validation ?? []),
+      ...(css.competitors ?? []),
+      ...(css.revenue_signals ?? []),
+      ...(css.technical_mechanisms ?? []),
+    ].slice(0, 8);
+    if (allSigs.length > 0) {
+      sigEl.textContent = "Signals detected: " + allSigs.join(" · ");
+      sigEl.hidden = false;
+    } else {
+      sigEl.hidden = true;
+    }
+  }
+
+  // Reordered: improved content first, then answers
+  document.getElementById("improved-answer").textContent = data.improved_answer ?? "";
+  document.getElementById("improved-pitch").textContent = data.improved_pitch ?? "";
+  document.getElementById("best-answer").textContent = data.best_answer ?? "";
+  document.getElementById("weakest-answer").textContent = data.weakest_answer ?? "";
+
+  const list = document.getElementById("top-questions");
+  list.innerHTML = "";
+  (data.top_3_questions ?? []).forEach((q) => {
+    const li = document.createElement("li");
+    li.textContent = q;
+    list.appendChild(li);
+  });
+}
+
+document.getElementById("btn-load-sample").addEventListener("click", loadSample);
+document.getElementById("btn-go-setup").addEventListener("click", () => showScreen("setup"));
+document.getElementById("btn-back-landing").addEventListener("click", () => showScreen("landing"));
+document.getElementById("btn-start-battle").addEventListener("click", startSession);
+document.getElementById("btn-end-battle").addEventListener("click", endBattle);
+document.getElementById("btn-reset").addEventListener("click", resetBattle);
+document.getElementById("btn-back-setup").addEventListener("click", () => showScreen("setup"));
+
+document.getElementById("btn-view-conversation").addEventListener("click", () => {
+  document.getElementById("btn-end-battle").hidden = true;
+  document.getElementById("btn-back-scorecard").hidden = false;
+  document.getElementById("chat-form").hidden = true;
+  showScreen("battle");
+  chatWindow.scrollTop = chatWindow.scrollHeight;
+});
+
+document.getElementById("btn-back-scorecard").addEventListener("click", () => {
+  document.getElementById("btn-end-battle").hidden = false;
+  document.getElementById("btn-back-scorecard").hidden = true;
+  document.getElementById("chat-form").hidden = false;
+  showScreen("scorecard");
+});
+
+document.querySelectorAll(".persona-card").forEach((card) => {
+  card.addEventListener("click", () => {
+    document.querySelectorAll(".persona-card").forEach((c) => c.classList.remove("selected"));
+    card.classList.add("selected");
+    state.persona = card.dataset.persona;
+  });
+});
+
+document.getElementById("chat-form").addEventListener("submit", (event) => {
+  event.preventDefault();
+  sendMessage();
+});
+
+function boot() {
+  console.log("PitchFight frontend booting...");
+  setGlobalLoading(false);
+  hideErrorBanner();
+
+  fetch("/health")
+    .then((response) => response.json())
+    .then((data) => console.log("Backend health:", data))
+    .catch((error) => {
+      console.warn("Health check failed:", error);
+      showErrorBanner(
+        "Backend health check failed. Run python app.py and refresh this page."
+      );
+    });
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", boot);
+} else {
+  boot();
+}

frontend/styles.css

@@ -0,0 +1,453 @@
+:root {
+  --bg: #06080f;
+  --bg-panel: rgba(18, 22, 36, 0.78);
+  --text: #f8f4e8;
+  --muted: #b9b3a4;
+  --red: #e63946;
+  --gold: #f4d35e;
+  --border: rgba(244, 211, 94, 0.18);
+  --shadow: 0 12px 40px rgba(0, 0, 0, 0.45);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: "Segoe UI", system-ui, sans-serif;
+  color: var(--text);
+  background: radial-gradient(circle at top, #12182a 0%, var(--bg) 55%);
+}
+
+.bg-glow {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  background:
+    radial-gradient(circle at 15% 20%, rgba(230, 57, 70, 0.18), transparent 35%),
+    radial-gradient(circle at 85% 10%, rgba(244, 211, 94, 0.12), transparent 30%);
+}
+
+.app {
+  position: relative;
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 2rem 1rem 3rem;
+}
+
+.screen {
+  display: none;
+}
+
+.screen.active {
+  display: block;
+}
+
+.glass {
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  border-radius: 18px;
+  backdrop-filter: blur(12px);
+  box-shadow: var(--shadow);
+}
+
+.hero {
+  text-align: center;
+  padding: 2rem 1rem;
+}
+
+.logo {
+  width: 88px;
+  height: 88px;
+  margin-bottom: 1rem;
+}
+
+h1 {
+  margin: 0;
+  font-size: clamp(2rem, 5vw, 3rem);
+  letter-spacing: 0.02em;
+}
+
+.tagline {
+  font-size: 1.15rem;
+  color: var(--gold);
+  margin: 0.75rem 0 0.35rem;
+}
+
+.subtitle {
+  color: var(--muted);
+  margin: 0;
+}
+
+.hero-actions {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin-top: 2rem;
+}
+
+.btn {
+  border: none;
+  border-radius: 12px;
+  padding: 0.85rem 1.25rem;
+  font-weight: 700;
+  cursor: pointer;
+  transition: transform 0.15s ease, box-shadow 0.15s ease, opacity 0.15s ease;
+}
+
+.btn:hover {
+  transform: translateY(-1px);
+}
+
+.btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.btn-primary {
+  color: #1a0b0d;
+  background: linear-gradient(135deg, var(--gold), #ffd86b);
+  box-shadow: 0 0 18px rgba(244, 211, 94, 0.35);
+}
+
+.btn-secondary {
+  color: var(--text);
+  background: rgba(255, 255, 255, 0.06);
+  border: 1px solid var(--border);
+}
+
+.btn-danger {
+  color: white;
+  background: linear-gradient(135deg, var(--red), #ff6b6b);
+  box-shadow: 0 0 18px rgba(230, 57, 70, 0.35);
+}
+
+.btn-ghost {
+  background: transparent;
+  color: var(--muted);
+  border: 1px solid transparent;
+}
+
+.btn-wide {
+  width: 100%;
+  margin-top: 1rem;
+}
+
+.panel {
+  padding: 1.25rem;
+  margin-bottom: 1.25rem;
+}
+
+.panel-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1rem;
+}
+
+.startup-form {
+  display: grid;
+  gap: 0.85rem;
+  margin-top: 1rem;
+}
+
+.startup-form label {
+  display: grid;
+  gap: 0.35rem;
+  font-size: 0.92rem;
+  color: var(--muted);
+}
+
+input,
+textarea {
+  width: 100%;
+  border-radius: 10px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(0, 0, 0, 0.25);
+  color: var(--text);
+  padding: 0.7rem 0.8rem;
+  font: inherit;
+}
+
+.persona-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 0.85rem;
+  margin-top: 1rem;
+}
+
+.persona-card {
+  text-align: left;
+  padding: 1rem;
+  border-radius: 14px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(0, 0, 0, 0.22);
+  color: var(--text);
+  cursor: pointer;
+  transition: border-color 0.15s ease, transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.persona-card:hover,
+.persona-card.selected {
+  border-color: var(--gold);
+  box-shadow: 0 0 16px rgba(244, 211, 94, 0.18);
+  transform: translateY(-2px);
+}
+
+.persona-card h3 {
+  margin: 0.35rem 0;
+}
+
+.persona-card p {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+
+.battle-layout {
+  display: grid;
+  grid-template-columns: 260px 1fr;
+  gap: 1rem;
+}
+
+.battle-meta {
+  padding: 1.25rem;
+}
+
+.meta-item {
+  display: flex;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.65rem 0;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.meta-item span {
+  color: var(--muted);
+}
+
+.pressure-medium { color: #7dd3fc; }
+.pressure-high { color: var(--gold); }
+.pressure-extreme { color: var(--red); }
+
+.battle-chat {
+  display: flex;
+  flex-direction: column;
+  min-height: 70vh;
+  padding: 1rem;
+}
+
+.chat-window {
+  flex: 1;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  padding: 0.5rem;
+  margin-bottom: 1rem;
+}
+
+.message {
+  max-width: 85%;
+  padding: 0.8rem 1rem;
+  border-radius: 14px;
+  line-height: 1.45;
+}
+
+.message.user {
+  align-self: flex-end;
+  background: rgba(230, 57, 70, 0.18);
+  border: 1px solid rgba(230, 57, 70, 0.35);
+}
+
+.message.ai {
+  align-self: flex-start;
+  background: rgba(244, 211, 94, 0.08);
+  border: 1px solid rgba(244, 211, 94, 0.22);
+}
+
+.message-meta {
+  display: block;
+  font-size: 0.75rem;
+  color: var(--gold);
+  margin-bottom: 0.35rem;
+}
+
+.chat-input-row {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 0.75rem;
+}
+
+.status-text {
+  color: var(--red);
+  font-size: 0.9rem;
+  margin: 0.5rem 0 0;
+}
+
+.scorecard-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1rem;
+}
+
+.scorecard-header-left {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.btn-sm {
+  padding: 0.3rem 0.75rem;
+  font-size: 0.8rem;
+  border-radius: 6px;
+  align-self: flex-start;
+}
+
+.overall-score {
+  text-align: right;
+}
+
+.overall-score strong {
+  display: block;
+  font-size: 2.5rem;
+  color: var(--gold);
+}
+
+.score-bars {
+  display: grid;
+  gap: 0.9rem;
+  margin: 1.25rem 0;
+}
+
+.score-row-head {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 0.35rem;
+  text-transform: capitalize;
+}
+
+.bar-track {
+  height: 10px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.08);
+  overflow: hidden;
+}
+
+.bar-fill {
+  height: 100%;
+  background: linear-gradient(90deg, var(--red), var(--gold));
+}
+
+.score-reason {
+  margin: 0.35rem 0 0;
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+
+.score-label {
+  margin-left: 0.5rem;
+  font-size: 0.75rem;
+  color: var(--gold);
+  font-weight: 600;
+  opacity: 0.85;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.feedback-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  gap: 0.85rem;
+}
+
+.feedback-card {
+  padding: 1rem;
+  border-radius: 12px;
+  background: rgba(0, 0, 0, 0.22);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.feedback-card.highlight {
+  border-color: rgba(244, 211, 94, 0.25);
+}
+
+.prep-questions {
+  margin-top: 1.25rem;
+}
+
+.scorecard-actions {
+  display: flex;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+  margin-top: 1.25rem;
+}
+
+.signals-summary {
+  font-size: 0.78rem;
+  color: var(--muted);
+  margin: 0.6rem 0 0.2rem;
+  padding: 0.4rem 0.75rem;
+  border-left: 2px solid rgba(244, 211, 94, 0.35);
+  line-height: 1.5;
+  word-break: break-word;
+}
+
+.error-banner {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 30;
+  padding: 0.85rem 1.25rem;
+  background: rgba(230, 57, 70, 0.92);
+  color: #fff;
+  font-weight: 600;
+  text-align: center;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.35);
+}
+
+.error-banner[hidden] {
+  display: none;
+}
+
+.loading-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+  display: grid;
+  place-items: center;
+  z-index: 20;
+}
+
+.loading-overlay[hidden] {
+  display: none;
+}
+
+.spinner {
+  width: 42px;
+  height: 42px;
+  border-radius: 50%;
+  border: 3px solid rgba(255, 255, 255, 0.15);
+  border-top-color: var(--gold);
+  animation: spin 0.8s linear infinite;
+  margin: 0 auto 0.75rem;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (max-width: 820px) {
+  .battle-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .chat-input-row {
+    grid-template-columns: 1fr;
+  }
+}

packages.txt

@@ -0,0 +1 @@
+ffmpeg

requirements.txt

@@ -0,0 +1,9 @@
+gradio>=5.0.0
+fastapi
+uvicorn
+pydantic
+python-dotenv
+numpy
+openai>=1.0.0
+httpx
+requests

scripts/test_claim_based_scoring.py

@@ -0,0 +1,336 @@
+"""Phase 5D: Local unit tests for claim extractor, local scoring, and session-aware fallback.
+
+No server required. Tests run purely locally.
+
+Usage:
+  python scripts/test_claim_based_scoring.py
+"""
+
+from __future__ import annotations
+
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from core.claim_extractor import extract_concrete_signals
+from core.scoring_engine import (
+    build_session_aware_fallback_scorecard,
+    _compute_local_scores,
+    _score_label,
+)
+from core.json_utils import _score_label as json_score_label
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    marker = "PASS" if condition else "FAIL"
+    suffix = f" — {detail}" if detail else ""
+    print(f"  {marker}  {label}{suffix}")
+    if not condition:
+        sys.exit(1)
+
+
+def make_session(answers: list[str], startup: dict | None = None) -> dict:
+    startup = startup or {
+        "name": "TestStartup",
+        "problem": "Test problem",
+        "solution": "Test solution",
+        "why_ai": "AI helps",
+        "stage": "Prototype",
+        "team": "2 founders",
+        "traction": "10 beta users",
+    }
+    history = []
+    for i, ans in enumerate(answers):
+        if i % 2 == 0:
+            history.append({"role": "assistant", "content": f"Judge question {i}", "attack_tag": "Market Size"})
+        history.append({"role": "user", "content": ans})
+    return {"startup": startup, "persona": "hackathon_judge", "difficulty": "high", "history": history}
+
+
+# ---------------------------------------------------------------------------
+# Extraction tests (existing)
+# ---------------------------------------------------------------------------
+
+def test_strong_evidence_answer() -> None:
+    print("\nTest 1: Strong evidence — numbers, validation, campus")
+    session = make_session(["80 users, 60% interview rate, 3 colleges have onboarded already."])
+    sigs = extract_concrete_signals(session)
+    check("numbers extracted", len(sigs["numbers"]) > 0, f"got {sigs['numbers']}")
+    check("percentages extracted", len(sigs["percentages"]) > 0, f"got {sigs['percentages']}")
+    check("college_mentions extracted", len(sigs["college_mentions"]) > 0, f"got {sigs['college_mentions']}")
+    check("signal_count > 0", sigs["signal_count"] > 0, f"got {sigs['signal_count']}")
+    check("non_answers empty", len(sigs["non_answers"]) == 0)
+    check("best_user_quotes non-empty", len(sigs["best_user_quotes"]) > 0)
+
+
+def test_vague_answer() -> None:
+    print("\nTest 2: Vague answer — big market, useful")
+    session = make_session(["It is useful and big market will love it."])
+    sigs = extract_concrete_signals(session)
+    check("vague_claims detected", len(sigs["vague_claims"]) > 0, f"got {sigs['vague_claims']}")
+    check("no numbers", len(sigs["numbers"]) == 0, f"got {sigs['numbers']}")
+
+
+def test_non_answer() -> None:
+    print("\nTest 3: Non-answer — 'I don't know'")
+    session = make_session(["I don't know"])
+    sigs = extract_concrete_signals(session)
+    check("non_answers detected", len(sigs["non_answers"]) > 0, f"got {sigs['non_answers']}")
+    check("best_user_quotes empty", len(sigs["best_user_quotes"]) == 0)
+    check("signal_count is 0", sigs["signal_count"] == 0, f"got {sigs['signal_count']}")
+
+
+def test_pricing_and_revenue() -> None:
+    print("\nTest 4: Pricing and revenue — ₹399 per student and CAC ~₹50")
+    session = make_session(["We charge ₹399 per student and our CAC is around ₹50."])
+    sigs = extract_concrete_signals(session)
+    check("pricing detected", len(sigs["pricing"]) > 0, f"got {sigs['pricing']}")
+    check("revenue_signals detected", len(sigs["revenue_signals"]) > 0, f"got {sigs['revenue_signals']}")
+    check("signal_count > 0", sigs["signal_count"] > 0)
+
+
+def test_competitors_and_tech() -> None:
+    print("\nTest 5: Competitors and technical mechanism")
+    session = make_session([
+        "Luma and LinkedIn are competitors but we use profile-based ranking with embedding models."
+    ])
+    sigs = extract_concrete_signals(session)
+    check("competitors detected", len(sigs["competitors"]) > 0, f"got {sigs['competitors']}")
+    check("technical_mechanisms detected", len(sigs["technical_mechanisms"]) > 0, f"got {sigs['technical_mechanisms']}")
+
+
+def test_mixed_session() -> None:
+    print("\nTest 6: Mixed session — strong + non-answer + vague")
+    session = make_session([
+        "We validated this with 50 beta users, 3 campus ambassadors, and weekly event-miss reports.",
+        "I don't know",
+        "It is a big market.",
+        "We use embeddings and a ranking model trained on student behavior.",
+    ])
+    sigs = extract_concrete_signals(session)
+    check("numbers detected", len(sigs["numbers"]) > 0, f"got {sigs['numbers']}")
+    check("validation detected", len(sigs["validation"]) > 0, f"got {sigs['validation']}")
+    check("non_answers detected", len(sigs["non_answers"]) > 0)
+    check("vague_claims detected", len(sigs["vague_claims"]) > 0)
+    check("technical_mechanisms detected", len(sigs["technical_mechanisms"]) > 0)
+    check("best_user_quotes >= 2", len(sigs["best_user_quotes"]) >= 2, f"got {len(sigs['best_user_quotes'])}")
+    check("signal_count > 3", sigs["signal_count"] > 3, f"got {sigs['signal_count']}")
+
+
+# ---------------------------------------------------------------------------
+# Local scoring tests (Phase 5D)
+# ---------------------------------------------------------------------------
+
+def test_local_scoring_strong_evidence() -> None:
+    print("\nTest 7: Local scoring — '80 users, 60% interview rate, 3 colleges' should get real credit")
+    session = make_session([
+        "80 users, 60% interview rate, 3 colleges have onboarded already.",
+        "We charge ₹399 per student and our CAC is around ₹50.",
+        "Luma and LinkedIn are competitors but we use profile-based ranking with embedding models.",
+    ])
+    sigs = extract_concrete_signals(session)
+    startup = session.get("startup", {})
+    scores, best_answer, weakest_answer, why_weak = _compute_local_scores(sigs, startup)
+
+    # All 6 dims must be present
+    required = {"clarity", "problem_understanding", "market_awareness",
+                "differentiation", "business_model", "objection_handling"}
+    check("all 6 dims present", required <= set(scores.keys()))
+
+    # With concrete evidence, most dims should be Developing (31+) or above
+    for dim in required:
+        s = scores[dim]["score"]
+        check(f"{dim}.score >= 30", s >= 30, f"got {s} — evidence was strong")
+
+    # Dims with direct evidence should be Solid (51+) or Strong
+    # market_awareness should get credit for numbers + competitors
+    market_s = scores["market_awareness"]["score"]
+    check("market_awareness >= 50 (has numbers + competitors)", market_s >= 50, f"got {market_s}")
+
+    # differentiation should get credit for competitors + tech
+    diff_s = scores["differentiation"]["score"]
+    check("differentiation >= 50 (has competitors + tech)", diff_s >= 50, f"got {diff_s}")
+
+    # business_model should get credit for ₹399 + CAC
+    biz_s = scores["business_model"]["score"]
+    check("business_model >= 45 (has pricing + revenue)", biz_s >= 45, f"got {biz_s}")
+
+    # best_answer should be non-empty
+    check("best_answer non-empty", bool(best_answer))
+    check("why_weak non-empty", bool(why_weak))
+
+
+def test_local_scoring_vague_floor() -> None:
+    print("\nTest 8: Local scoring — vague on-topic answer should not go below 30 (global floor)")
+    session = make_session([
+        "It is a big market because students attend events often.",
+        "We have a better AI solution than others.",
+    ])
+    sigs = extract_concrete_signals(session)
+    startup = session.get("startup", {})
+    scores, _, _, _ = _compute_local_scores(sigs, startup)
+
+    # On-topic engagement = engagement > 0, so floor is 33
+    for dim, data in scores.items():
+        s = data["score"]
+        # Some dims may dip below 33 (business_model has 28 floor), but most should be >= 30
+        if dim != "business_model":
+            check(f"{dim}.score >= 30 (vague but on-topic)", s >= 30, f"got {s}")
+
+
+def test_local_scoring_non_answer_can_be_below_30() -> None:
+    print("\nTest 9: Local scoring — all non-answers can score below 30")
+    session = make_session(["ok", "I don't know", "yeah", "not sure"])
+    sigs = extract_concrete_signals(session)
+    startup = session.get("startup", {})
+    scores, _, _, _ = _compute_local_scores(sigs, startup)
+
+    # With all non-answers, engagement=0, so dims should be low
+    low_count = sum(1 for d in scores.values() if d["score"] <= 20)
+    check("majority of dims <= 20 when all non-answers", low_count >= 4,
+          f"got {low_count} dims <= 20, scores={[(k, v['score']) for k, v in scores.items()]}")
+
+
+def test_local_scoring_pricing_revenue() -> None:
+    print("\nTest 10: Local scoring — ₹399 and CAC ₹50 → business_model Developing or better")
+    session = make_session(["We charge ₹399 per student and our CAC is around ₹50."])
+    sigs = extract_concrete_signals(session)
+    startup = session.get("startup", {})
+    scores, _, _, _ = _compute_local_scores(sigs, startup)
+
+    biz_s = scores["business_model"]["score"]
+    biz_lbl = scores["business_model"]["label"]
+    check(
+        "business_model >= 31 (Developing or better) with ₹399 + CAC",
+        biz_s >= 31,
+        f"got {biz_s} ({biz_lbl})",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Session-aware fallback test
+# ---------------------------------------------------------------------------
+
+def test_session_aware_fallback_not_static() -> None:
+    print("\nTest 11: Session-aware fallback does not return EventRadar static content")
+    session = make_session(
+        [
+            "We have 80 users at IIT Delhi and IIT Bombay paying ₹499/month.",
+            "Competitors are LinkedIn and Glassdoor but we do skill-gap analysis.",
+        ],
+        startup={
+            "name": "SkillBridge",
+            "problem": "Students get rejected because their resume skills don't match job requirements.",
+            "solution": "AI that maps resume skills to actual job description gaps.",
+            "why_ai": "Personalized skill-gap analysis requires LLM understanding.",
+            "stage": "Beta",
+            "team": "2 founders",
+            "traction": "80 paying users",
+        },
+    )
+    sigs = extract_concrete_signals(session)
+    fb = build_session_aware_fallback_scorecard(session, sigs, "test error")
+
+    check("scorecard_source=session_fallback", fb.get("scorecard_source") == "session_fallback")
+    check("model_ok=False", fb.get("model_ok") is False)
+    check("provider=local", fb.get("provider") == "local")
+    check("model_error present", bool(fb.get("model_error")))
+    check("overall is int 0-100",
+          isinstance(fb.get("overall"), int) and 0 <= fb.get("overall", -1) <= 100)
+    check("overall_label valid",
+          fb.get("overall_label") in {"Not addressed", "Developing", "Solid", "Strong", "Excellent"})
+    check("all 6 dims present",
+          {"clarity", "problem_understanding", "market_awareness",
+           "differentiation", "business_model", "objection_handling"}
+          <= set(fb.get("scores", {}).keys()))
+    check("concrete_signals_summary present", isinstance(fb.get("concrete_signals_summary"), dict))
+    check("top_3_questions has 3", len(fb.get("top_3_questions", [])) == 3)
+
+    full_text = str(fb)
+    for phrase in ["WhatsApp groups", "EventRadar"]:
+        check(
+            f"no static phrase '{phrase}' in session fallback",
+            phrase not in full_text or "SkillBridge" in full_text,
+        )
+
+    best = fb.get("best_answer", "")
+    check(
+        "best_answer contains actual answer text",
+        any(word in best for word in ["80 users", "IIT", "499", "SkillBridge", "LinkedIn", "skill"]),
+        f"got: {best[:120]}",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Score label band tests
+# ---------------------------------------------------------------------------
+
+def test_score_label_bands() -> None:
+    print("\nTest 12: Score label bands (Phase 5C/5D)")
+    cases = [
+        (0,   "Not addressed"),
+        (15,  "Not addressed"),
+        (30,  "Not addressed"),
+        (31,  "Developing"),
+        (50,  "Developing"),
+        (51,  "Solid"),
+        (70,  "Solid"),
+        (71,  "Strong"),
+        (85,  "Strong"),
+        (86,  "Excellent"),
+        (100, "Excellent"),
+    ]
+    for score, expected in cases:
+        got = _score_label(score)
+        check(f"_score_label({score}) == '{expected}'", got == expected, f"got '{got}'")
+    # Also verify json_utils._score_label matches
+    for score, expected in cases:
+        got = json_score_label(score)
+        check(f"json_utils._score_label({score}) == '{expected}'", got == expected, f"got '{got}'")
+
+
+def test_all_non_answer_session() -> None:
+    print("\nTest 13: All non-answer session — fallback should still work")
+    session = make_session(["ok", "I don't know", "yeah", "not sure"])
+    sigs = extract_concrete_signals(session)
+    check("all are non_answers", len(sigs["non_answers"]) >= 3)
+    check("signal_count=0", sigs["signal_count"] == 0)
+    fb = build_session_aware_fallback_scorecard(session, sigs)
+    check("fallback returns valid dict", isinstance(fb, dict))
+    check("overall >= 0", fb.get("overall", -1) >= 0)
+    check("scorecard_source=session_fallback", fb.get("scorecard_source") == "session_fallback")
+
+
+# ---------------------------------------------------------------------------
+# Runner
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    print("\nPhase 5D — Claim Extractor + Local Scoring + Session-Aware Fallback Tests")
+    print("(No server required)\n")
+
+    test_strong_evidence_answer()
+    test_vague_answer()
+    test_non_answer()
+    test_pricing_and_revenue()
+    test_competitors_and_tech()
+    test_mixed_session()
+    test_local_scoring_strong_evidence()
+    test_local_scoring_vague_floor()
+    test_local_scoring_non_answer_can_be_below_30()
+    test_local_scoring_pricing_revenue()
+    test_session_aware_fallback_not_static()
+    test_score_label_bands()
+    test_all_non_answer_session()
+
+    print("\nAll Phase 5D claim-based scoring tests passed.\n")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_nvidia_client.py

@@ -0,0 +1,90 @@
+"""Isolated NVIDIA Nemotron connectivity test.
+
+Run from the project root:
+    python scripts/test_nvidia_client.py
+
+Exits 0 on success, 1 on failure.
+Does not expose the API key in output.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Allow imports from project root regardless of working directory
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from core.nvidia_client import health_check, generate_nemotron_response  # noqa: E402
+
+
+def main() -> int:
+    print("=" * 60)
+    print("PitchFight AI — NVIDIA Nemotron connectivity test")
+    print("=" * 60)
+
+    # 1. Health check (no key in output)
+    print("\n[1] Health check")
+    status = health_check()
+    print(f"  provider    : {status['provider']}")
+    print(f"  configured  : {status['configured']}")
+    print(f"  base_url    : {status['base_url']}")
+    print(f"  model       : {status['model']}")
+    print(f"  key present : {status['api_key_present']}")
+    print(f"  message     : {status['message']}")
+
+    if not status["configured"]:
+        print("\n[FAIL] NVIDIA_API_KEY is not set.")
+        print("  Add it to your .env file and re-run this script.")
+        return 1
+
+    # 2. Test prompt
+    print("\n[2] Sending test prompt to Nemotron...")
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are a skeptical hackathon judge. "
+                "Ask exactly one sharp question. Do not give advice."
+            ),
+        },
+        {
+            "role": "user",
+            "content": (
+                "Startup: EventRadar AI.\n"
+                "Problem: Students miss hackathons and tech events because "
+                "discovery is scattered.\n"
+                "Solution: AI-powered event discovery that ranks opportunities "
+                "by skills, goals, location, and deadline urgency.\n\n"
+                "Return exactly one question under 40 words."
+            ),
+        },
+    ]
+
+    try:
+        response = generate_nemotron_response(
+            messages,
+            mode="opponent",
+            temperature=0.7,
+            timeout=30,
+        )
+        print("\n[3] Model response:")
+        print("-" * 40)
+        print(response)
+        print("-" * 40)
+        print("\n[PASS] NVIDIA Nemotron responded successfully.")
+        print("Phase 2 model connectivity: OK")
+        return 0
+
+    except RuntimeError as exc:
+        print(f"\n[FAIL] {exc}")
+        print("Check your NVIDIA_API_KEY and NVIDIA_BASE_URL in .env")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/test_phase3_pitch_battle.py

@@ -0,0 +1,123 @@
+"""Phase 3 end-to-end test: live pitch battle via the running server.
+
+Usage:
+  python scripts/test_phase3_pitch_battle.py
+
+Requires the server to already be running. Set PITCHFIGHT_BASE_URL to override
+the default base URL (http://127.0.0.1:7861).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import requests
+
+BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
+
+SAMPLE_STARTUP = {
+    "name": "EventRadar AI",
+    "problem": "Students miss relevant hackathons, workshops, and networking events.",
+    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
+    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
+    "stage": "Prototype",
+    "team": "2 founders",
+    "traction": "50 beta signups, no revenue yet",
+}
+
+USER_ANSWER = (
+    "It is a pretty big market because students attend events often."
+)
+
+
+def post(path: str, body: dict) -> dict:
+    url = f"{BASE_URL}{path}"
+    resp = requests.post(url, json=body, timeout=60)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    if condition:
+        print(f"  PASS  {label}")
+    else:
+        print(f"  FAIL  {label}" + (f" — {detail}" if detail else ""))
+        sys.exit(1)
+
+
+def main() -> None:
+    print(f"\nPhase 3 Pitch Battle Test\nBase URL: {BASE_URL}\n")
+
+    # --- Step 1: start-session ---
+    print("Step 1: POST /api/start-session")
+    try:
+        data = post("/api/start-session", {
+            "mode": "pitch_battle",
+            "startup": SAMPLE_STARTUP,
+            "persona": "hackathon_judge",
+            "difficulty": "high",
+            "input_mode": "text",
+            "model_mode": "premium_nvidia",
+        })
+    except Exception as exc:
+        print(f"  FAIL  Request failed: {exc}")
+        sys.exit(1)
+
+    print(f"  session_id : {data.get('session_id', '—')}")
+    print(f"  model_ok   : {data.get('model_ok')}")
+    print(f"  provider   : {data.get('provider')}")
+    print(f"  model_mode : {data.get('model_mode')}")
+    print(f"  attack_tag : {data.get('attack_tag')}")
+    print(f"  round      : {data.get('round')}")
+    print(f"  ai_message :\n    {data.get('ai_message', '')}\n")
+
+    session_id = data.get("session_id")
+    check("session_id present", bool(session_id), "got empty session_id")
+    check("ai_message non-empty", bool(data.get("ai_message")), "ai_message is empty")
+    check("round is 1", data.get("round") == 1, f"got {data.get('round')}")
+    check("attack_tag present", bool(data.get("attack_tag")))
+
+    if data.get("model_ok"):
+        check("provider is nvidia", data.get("provider") == "nvidia")
+    else:
+        print("  NOTE  Model returned mock fallback (NVIDIA may be down or key missing)")
+        if data.get("model_error"):
+            print(f"  model_error: {data['model_error']}")
+
+    # --- Step 2: chat-round ---
+    print("\nStep 2: POST /api/chat-round")
+    try:
+        data2 = post("/api/chat-round", {
+            "session_id": session_id,
+            "user_message": USER_ANSWER,
+        })
+    except Exception as exc:
+        print(f"  FAIL  Request failed: {exc}")
+        sys.exit(1)
+
+    print(f"  model_ok   : {data2.get('model_ok')}")
+    print(f"  provider   : {data2.get('provider')}")
+    print(f"  model_mode : {data2.get('model_mode')}")
+    print(f"  attack_tag : {data2.get('attack_tag')}")
+    print(f"  round      : {data2.get('round')}")
+    print(f"  ai_message :\n    {data2.get('ai_message', '')}\n")
+
+    check("session_id echoed", data2.get("session_id") == session_id)
+    check("ai_message non-empty", bool(data2.get("ai_message")), "ai_message is empty")
+    check("round is 2", data2.get("round") == 2, f"got {data2.get('round')}")
+
+    if data2.get("model_ok"):
+        check("provider is nvidia", data2.get("provider") == "nvidia")
+    else:
+        print("  NOTE  chat-round returned mock fallback")
+        if data2.get("model_error"):
+            print(f"  model_error: {data2['model_error']}")
+
+    print("\nAll checks passed. Phase 3 integration is working.\n")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_phase3b_battle_flow.py

@@ -0,0 +1,217 @@
+"""Phase 3B end-to-end test: Socratic judge flow via the running server.
+
+Validates:
+  - answer_quality classification appears in chat-round responses
+  - judge_action drives tag switching / follow-up decisions
+  - Same attack tag not repeated more than MAX_ATTEMPTS_PER_ATTACK_TAG times
+  - ai_message is always non-empty (model or mock fallback)
+  - All required response fields are present
+
+Usage:
+  python scripts/test_phase3b_battle_flow.py
+
+Server must already be running. Set PITCHFIGHT_BASE_URL to override default.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections import defaultdict
+
+import requests
+
+BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
+
+SAMPLE_STARTUP = {
+    "name": "EventRadar AI",
+    "problem": "Students miss relevant hackathons, workshops, and networking events.",
+    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
+    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
+    "stage": "Prototype",
+    "team": "2 founders",
+    "traction": "50 beta signups, no revenue yet",
+}
+
+STRONG_ANSWER = (
+    "We validated this with 50 beta users, 3 campus ambassadors, "
+    "and weekly event-miss reports from two colleges."
+)
+
+ANSWERS = [
+    "It is a pretty big market because students attend events often.",  # weak
+    "I don't know",                                                      # non_answer
+    "ok",                                                                # non_answer → triggers move_after_limit
+    STRONG_ANSWER,                                                       # strong → move_next_tag
+    "The AI personalizes event ranking based on student goals.",         # partial
+]
+
+MAX_ATTEMPTS_ALLOWED = 2  # must match battle_flow.MAX_ATTEMPTS_PER_ATTACK_TAG
+
+
+def post(path: str, body: dict) -> dict:
+    url = f"{BASE_URL}{path}"
+    resp = requests.post(url, json=body, timeout=60)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    marker = "PASS" if condition else "FAIL"
+    suffix = f" — {detail}" if detail else ""
+    print(f"  {marker}  {label}{suffix}")
+    if not condition:
+        sys.exit(1)
+
+
+def main() -> None:
+    print(f"\nPhase 3B Battle Flow Test\nBase URL: {BASE_URL}\n")
+
+    # --- start-session ---
+    print("Step 0: POST /api/start-session")
+    try:
+        start = post("/api/start-session", {
+            "mode": "pitch_battle",
+            "startup": SAMPLE_STARTUP,
+            "persona": "hackathon_judge",
+            "difficulty": "high",
+            "input_mode": "text",
+            "model_mode": "premium_nvidia",
+        })
+    except Exception as exc:
+        print(f"  FAIL  Request failed: {exc}")
+        sys.exit(1)
+
+    session_id = start.get("session_id")
+    check("session_id present", bool(session_id))
+    check("ai_message non-empty", bool(start.get("ai_message")))
+    check("judge_action = opening_question", start.get("judge_action") == "opening_question",
+          f"got {start.get('judge_action')!r}")
+    check("answer_quality is None", start.get("answer_quality") is None,
+          f"got {start.get('answer_quality')!r}")
+    check("tag_attempt = 1", start.get("tag_attempt") == 1, f"got {start.get('tag_attempt')!r}")
+
+    opening_tag = start.get("attack_tag")
+    print(f"  opening attack_tag : {opening_tag}")
+    print(f"  ai_message         : {start['ai_message'][:120]}...\n")
+
+    # Track tag attempt counts locally to verify the invariant
+    tag_attempts: dict[str, int] = defaultdict(int)
+    tag_attempts[opening_tag] += 1
+
+    rounds: list[dict] = []
+
+    # --- chat rounds ---
+    for i, answer in enumerate(ANSWERS, start=1):
+        round_num = i + 1  # round 1 was the opening
+        print(f"Step {i}: POST /api/chat-round  (sending: {answer!r})")
+
+        try:
+            data = post("/api/chat-round", {
+                "session_id": session_id,
+                "user_message": answer,
+            })
+        except Exception as exc:
+            print(f"  FAIL  Request failed: {exc}")
+            sys.exit(1)
+
+        atag = data.get("attack_tag", "")
+        aq = data.get("answer_quality", "")
+        ja = data.get("judge_action", "")
+        attempt = data.get("tag_attempt", 0)
+        satisfied = data.get("topic_satisfied")
+        prev_tag = data.get("previous_attack_tag", "")
+
+        # Update local tracking
+        tag_attempts[atag] += 1
+
+        print(f"  round              : {data.get('round')}")
+        print(f"  attack_tag         : {atag}")
+        print(f"  previous_tag       : {prev_tag}")
+        print(f"  answer_quality     : {aq}")
+        print(f"  judge_action       : {ja}")
+        print(f"  tag_attempt        : {attempt}")
+        print(f"  topic_satisfied    : {satisfied}")
+        print(f"  model_ok           : {data.get('model_ok')}")
+        print(f"  provider           : {data.get('provider')}")
+        print(f"  ai_message         : {data.get('ai_message', '')[:120]}...\n")
+
+        # Required field checks
+        check("session_id echoed", data.get("session_id") == session_id)
+        check("ai_message non-empty", bool(data.get("ai_message")), "ai_message is empty")
+        check("attack_tag present", bool(atag))
+        check("answer_quality present", aq in ("strong", "partial", "weak", "non_answer"),
+              f"got {aq!r}")
+        check("judge_action present", ja in ("follow_up_same_tag", "move_next_tag", "move_after_limit"),
+              f"got {ja!r}")
+        check("tag_attempt present", isinstance(attempt, int) and attempt >= 1,
+              f"got {attempt!r}")
+        check("provider present", bool(data.get("provider")))
+
+        rounds.append(data)
+
+    # --- Invariant: no tag exceeded MAX_ATTEMPTS_ALLOWED across all rounds ---
+    print("Invariant check: no attack_tag exceeded MAX_ATTEMPTS_PER_ATTACK_TAG")
+    for tag, count in tag_attempts.items():
+        if tag in ("Round Limit", "Session Error"):
+            continue
+        check(
+            f"  tag '{tag}' attempts <= {MAX_ATTEMPTS_ALLOWED}",
+            count <= MAX_ATTEMPTS_ALLOWED,
+            f"got {count} attempts",
+        )
+
+    # --- Verify first weak answer triggered follow_up_same_tag (not a random jump) ---
+    first = rounds[0]
+    first_ja = first.get("judge_action", "")
+    check(
+        "First weak answer → follow_up or move (not random jump)",
+        first_ja in ("follow_up_same_tag", "move_after_limit", "move_next_tag"),
+        f"got {first_ja!r}",
+    )
+
+    # --- Verify third answer ("ok") did not keep drilling the same tag forever ---
+    if len(rounds) >= 3:
+        third_ja = rounds[2].get("judge_action", "")
+        check(
+            "After 2nd non-answer on same tag, judge moved or pressed (no infinite loop)",
+            third_ja in ("move_after_limit", "move_next_tag", "follow_up_same_tag"),
+            f"got {third_ja!r}",
+        )
+
+    # --- Strong-answer checks (rounds[3] = STRONG_ANSWER) ---
+    if len(rounds) >= 4:
+        strong_round = rounds[3]
+        strong_ja = strong_round.get("judge_action", "")
+        strong_tag = strong_round.get("attack_tag", "")
+        strong_prev = strong_round.get("previous_attack_tag", "")
+        strong_satisfied = strong_round.get("topic_satisfied")
+
+        print("\nStrong-answer invariant checks:")
+        check(
+            "Strong answer → judge_action is move_next_tag",
+            strong_ja == "move_next_tag",
+            f"got {strong_ja!r}",
+        )
+        check(
+            "Strong answer → attack_tag changed from previous_attack_tag",
+            strong_tag != strong_prev,
+            f"both are {strong_tag!r} — judge did not advance",
+        )
+        check(
+            "Strong answer → topic_satisfied is True",
+            strong_satisfied is True,
+            f"got {strong_satisfied!r}",
+        )
+        check(
+            "Strong answer → answer_quality is 'strong'",
+            strong_round.get("answer_quality") == "strong",
+            f"got {strong_round.get('answer_quality')!r}",
+        )
+
+    print("\nAll Phase 3B checks passed. Socratic battle flow is working.\n")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_phase4_battle_stability.py

@@ -0,0 +1,261 @@
+"""Phase 4 stability test: full battle lifecycle via the running server.
+
+Validates:
+  - Battle runs cleanly from start to and beyond MAX_ROUNDS
+  - Strong answer causes move_next_tag with different attack_tag
+  - No attack_tag exceeds 2 attempts
+  - At round >= MAX_ROUNDS: soft_round_limit_reached=True, battle_complete=False, can_continue=True
+  - Chat continues working after MAX_ROUNDS (no hard block)
+  - /api/end-battle returns a scorecard dict (even if mock)
+  - Every ai_message is non-empty throughout
+  - No ai_message contains instruction leakage patterns
+
+Usage:
+  python scripts/test_phase4_battle_stability.py
+  PITCHFIGHT_BASE_URL=http://localhost:7861 python scripts/test_phase4_battle_stability.py
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections import defaultdict
+
+import requests
+
+BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
+MAX_ROUNDS = int(os.getenv("MAX_ROUNDS", "6"))
+
+SAMPLE_STARTUP = {
+    "name": "EventRadar AI",
+    "problem": "Students miss relevant hackathons, workshops, and networking events.",
+    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
+    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
+    "stage": "Prototype",
+    "team": "2 founders",
+    "traction": "50 beta signups, no revenue yet",
+}
+
+STRONG_ANSWER = (
+    "We validated this with 50 beta users, 3 campus ambassadors, "
+    "and weekly event-miss reports from two colleges."
+)
+
+# Sequence designed to exercise all branches: weak → non_answer → strong → partial → weak → strong
+ANSWER_SEQUENCE = [
+    "It is a pretty big market because students attend events often.",   # weak
+    "I don't know",                                                       # non_answer
+    STRONG_ANSWER,                                                        # strong → move_next_tag
+    "The AI ranks events based on student interest profiles.",            # partial
+    "okay fine",                                                          # non_answer
+    "We use embeddings and a ranking model trained on student behavior.", # strong (technical)
+    "It is useful and helpful for everyone.",                             # weak — beyond MAX_ROUNDS
+]
+
+_LEAKAGE_PATTERNS = re.compile(
+    r"we need to\b|the prompt says\b|as instructed\b|my instructions\b"
+    r"|i am supposed to\b|i should follow\b|the rules say\b|per the instructions?\b",
+    re.IGNORECASE,
+)
+
+
+def post(path: str, body: dict, timeout: int = 90) -> dict:
+    resp = requests.post(f"{BASE_URL}{path}", json=body, timeout=timeout)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    marker = "PASS" if condition else "FAIL"
+    suffix = f" — {detail}" if detail else ""
+    print(f"  {marker}  {label}{suffix}")
+    if not condition:
+        sys.exit(1)
+
+
+def main() -> None:
+    print(f"\nPhase 4 Battle Stability Test (Soft Round Limit)")
+    print(f"Base URL  : {BASE_URL}")
+    print(f"MAX_ROUNDS: {MAX_ROUNDS}\n")
+
+    # -------------------------------------------------------------------------
+    # Step 0: Start session
+    # -------------------------------------------------------------------------
+    print("Step 0: POST /api/start-session")
+    try:
+        start = post("/api/start-session", {
+            "mode": "pitch_battle",
+            "startup": SAMPLE_STARTUP,
+            "persona": "hackathon_judge",
+            "difficulty": "high",
+            "input_mode": "text",
+            "model_mode": "premium_nvidia",
+        })
+    except Exception as exc:
+        print(f"  FAIL  Request failed: {exc}")
+        sys.exit(1)
+
+    session_id = start.get("session_id")
+    check("session_id present", bool(session_id))
+    check("ai_message non-empty", bool(start.get("ai_message")))
+    check("round == 1", start.get("round") == 1, f"got {start.get('round')}")
+    check("judge_action == opening_question", start.get("judge_action") == "opening_question")
+    check("battle_complete=False at start", start.get("battle_complete") is False)
+    check("can_continue=True at start", start.get("can_continue") is True)
+
+    opening_tag = start.get("attack_tag")
+    print(f"  opening_tag  : {opening_tag}")
+    print(f"  battle_phase : {start.get('battle_phase')}")
+    print(f"  ai_message   : {start['ai_message'][:100]}...\n")
+
+    check(
+        "start ai_message has no leakage",
+        not _LEAKAGE_PATTERNS.search(start.get("ai_message", "")),
+        "instruction leakage detected in opening message",
+    )
+
+    # -------------------------------------------------------------------------
+    # Steps 1..MAX_ROUNDS+1: chat rounds (one beyond soft limit)
+    # -------------------------------------------------------------------------
+    tag_attempt_counts: dict[str, int] = defaultdict(int)
+    tag_attempt_counts[opening_tag] += 1
+
+    rounds: list[dict] = []
+    strong_round_idx: int | None = None
+
+    answers_to_send = ANSWER_SEQUENCE[: MAX_ROUNDS + 1]  # include one beyond soft limit
+
+    for i, answer in enumerate(answers_to_send):
+        print(f"Step {i + 1}: POST /api/chat-round  answer={answer[:60]!r}")
+        try:
+            data = post("/api/chat-round", {
+                "session_id": session_id,
+                "user_message": answer,
+            })
+        except Exception as exc:
+            print(f"  FAIL  Request failed: {exc}")
+            sys.exit(1)
+
+        atag     = data.get("attack_tag", "")
+        aq       = data.get("answer_quality", "")
+        ja       = data.get("judge_action", "")
+        prev_tag = data.get("previous_attack_tag", "")
+        rnd      = data.get("round", 0)
+        bc       = data.get("battle_complete", True)
+        cc       = data.get("can_continue", False)
+        na       = data.get("next_action", "")
+        sl       = data.get("soft_round_limit_reached", False)
+        phase    = data.get("battle_phase", "")
+
+        if atag not in ("Round Limit", "Session Error", ""):
+            tag_attempt_counts[atag] += 1
+
+        print(f"  round                   : {rnd}")
+        print(f"  battle_phase            : {phase}")
+        print(f"  attack_tag              : {atag}")
+        print(f"  prev_tag                : {prev_tag}")
+        print(f"  answer_quality          : {aq}")
+        print(f"  judge_action            : {ja}")
+        print(f"  battle_complete         : {bc}  can_continue: {cc}  next_action: {na}")
+        print(f"  soft_round_limit_reached: {sl}")
+        print(f"  model_ok                : {data.get('model_ok')}  provider: {data.get('provider')}")
+        print(f"  ai_message              : {data.get('ai_message', '')[:100]}...\n")
+
+        # Required fields
+        check("session_id echoed", data.get("session_id") == session_id)
+        check("ai_message non-empty", bool(data.get("ai_message")), "empty ai_message")
+        check("attack_tag present", bool(atag))
+        check("provider present", bool(data.get("provider")))
+        check("model_mode present", bool(data.get("model_mode")))
+
+        # battle_complete must always be False (soft limit only)
+        check("battle_complete always False", bc is False, f"got {bc!r}")
+        check("can_continue always True", cc is True, f"got {cc!r}")
+        check("next_action always continue", na == "continue", f"got {na!r}")
+
+        # Soft limit flag
+        if rnd >= MAX_ROUNDS:
+            check("soft_round_limit_reached=True at/after MAX_ROUNDS", sl is True, f"got {sl!r}")
+            check(
+                "recommended_action=end_battle when soft limit",
+                data.get("recommended_action") == "end_battle",
+                f"got {data.get('recommended_action')!r}",
+            )
+        else:
+            check("soft_round_limit_reached=False before MAX_ROUNDS", sl is False, f"got {sl!r}")
+
+        # Valid answer quality and judge action on normal rounds
+        if atag not in ("Round Limit",):
+            check(
+                "answer_quality valid",
+                aq in ("strong", "partial", "weak", "non_answer"),
+                f"got {aq!r}",
+            )
+            check(
+                "judge_action valid",
+                ja in ("follow_up_same_tag", "move_next_tag", "move_after_limit"),
+                f"got {ja!r}",
+            )
+
+        # No leakage
+        ai_msg = data.get("ai_message", "")
+        check(
+            "ai_message has no instruction leakage",
+            not _LEAKAGE_PATTERNS.search(ai_msg),
+            "instruction leakage detected",
+        )
+
+        # battle_phase progression
+        if rnd <= 3:
+            check("battle_phase=explore in rounds 1-3", phase == "explore", f"got {phase!r}")
+        elif rnd <= 6:
+            check("battle_phase=pressure in rounds 4-6", phase == "pressure", f"got {phase!r}")
+        else:
+            check("battle_phase=close in rounds 7+", phase == "close", f"got {phase!r}")
+
+        # Strong answer invariant
+        if aq == "strong" and strong_round_idx is None:
+            strong_round_idx = i
+            check("Strong answer → judge_action is move_next_tag", ja == "move_next_tag", f"got {ja!r}")
+            check("Strong answer → attack_tag changed", atag != prev_tag, f"both are {atag!r}")
+            check("Strong answer → topic_satisfied is True", data.get("topic_satisfied") is True)
+
+        rounds.append(data)
+
+    # -------------------------------------------------------------------------
+    # Invariant: no attack_tag exceeded 2 attempts
+    # -------------------------------------------------------------------------
+    print("Invariant: no attack_tag exceeded MAX_ATTEMPTS_PER_ATTACK_TAG (2)")
+    for tag, count in tag_attempt_counts.items():
+        if tag in ("Round Limit", "Session Error", ""):
+            continue
+        check(f"  tag '{tag}' attempts <= 2", count <= 2, f"got {count}")
+
+    # -------------------------------------------------------------------------
+    # /api/end-battle — must return a scorecard dict (mock is fine)
+    # -------------------------------------------------------------------------
+    print("\nStep final: POST /api/end-battle")
+    try:
+        scorecard = post("/api/end-battle", {"session_id": session_id})
+    except Exception as exc:
+        print(f"  FAIL  end-battle request failed: {exc}")
+        sys.exit(1)
+
+    print(f"  overall         : {scorecard.get('overall')}")
+    print(f"  overall_label   : {scorecard.get('overall_label')}")
+    print(f"  scorecard_source: {scorecard.get('scorecard_source')}")
+    print(f"  keys            : {list(scorecard.keys())}")
+
+    check("end-battle returns dict", isinstance(scorecard, dict))
+    check("no error in end-battle", "error" not in scorecard, f"error={scorecard.get('error')}")
+    check("overall score present", "overall" in scorecard, f"keys={list(scorecard.keys())}")
+    check("overall_label present", "overall_label" in scorecard)
+    check("scorecard_source present", "scorecard_source" in scorecard)
+
+    print("\nAll Phase 4 stability checks passed.\n")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_phase5_scorecard.py

@@ -0,0 +1,329 @@
+"""Phase 5D scorecard test: hybrid claim-based scoring via the running server.
+
+Validates:
+  - /api/end-battle returns all required fields
+  - All 6 score dimensions present with integer scores 0-100
+  - Score labels use 5-band scheme (Not addressed / Developing / Solid / Strong / Excellent)
+  - top_3_questions has exactly 3 items
+  - model_ok, provider, scorecard_source present
+  - concrete_signals_summary present with required sub-keys
+  - scorecard_source in ("hybrid_claims_nemotron", "hybrid_claims_local")
+  - provider in ("local+nvidia", "local")
+  - Set STRICT_NEMOTRON_COACHING=true to fail if not hybrid_claims_nemotron
+  - Conversation includes "50 beta users" and "3 campus ambassadors" →
+    expect these signals to appear in concrete_signals_summary or scores
+  - No old static mock content
+
+Usage:
+  python scripts/test_phase5_scorecard.py
+  PITCHFIGHT_BASE_URL=http://localhost:7861 python scripts/test_phase5_scorecard.py
+  STRICT_NEMOTRON_COACHING=true python scripts/test_phase5_scorecard.py
+
+Server must already be running (python app.py).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+import requests
+
+BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
+STRICT_COACHING = os.getenv("STRICT_NEMOTRON_COACHING", "false").strip().lower() == "true"
+# Legacy flag kept for compatibility
+ALLOW_FALLBACK = os.getenv("ALLOW_SCORECARD_FALLBACK", "false").strip().lower() == "true"
+
+SAMPLE_STARTUP = {
+    "name": "EventRadar AI",
+    "problem": "Students miss relevant hackathons, workshops, and networking events.",
+    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
+    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
+    "stage": "Prototype",
+    "team": "2 founders",
+    "traction": "50 beta signups, no revenue yet",
+}
+
+STRONG_ANSWER = (
+    "We validated this with 50 beta users, 3 campus ambassadors, "
+    "and weekly event-miss reports from two colleges."
+)
+
+ANSWERS = [
+    "It is a big market because students attend events often.",    # weak
+    "I don't know",                                               # non_answer
+    STRONG_ANSWER,                                                # strong → evidence
+    "The AI personalizes event ranking based on student goals.",  # partial
+]
+
+REQUIRED_DIMS = {
+    "clarity",
+    "problem_understanding",
+    "market_awareness",
+    "differentiation",
+    "business_model",
+    "objection_handling",
+}
+
+_VALID_LABELS = {"Not addressed", "Developing", "Solid", "Strong", "Excellent"}
+_VALID_SOURCES = {"hybrid_claims_nemotron", "hybrid_claims_local"}
+_VALID_PROVIDERS = {"local+nvidia", "local"}
+
+_LEAKAGE = re.compile(
+    r"we need to\b|the prompt says\b|as instructed\b|my instructions\b"
+    r"|i am supposed to\b|the rules say\b",
+    re.IGNORECASE,
+)
+
+
+def post(path: str, body: dict, timeout: int = 120) -> dict:
+    resp = requests.post(f"{BASE_URL}{path}", json=body, timeout=timeout)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    marker = "PASS" if condition else "FAIL"
+    suffix = f" — {detail}" if detail else ""
+    print(f"  {marker}  {label}{suffix}")
+    if not condition:
+        sys.exit(1)
+
+
+def main() -> None:
+    print(f"\nPhase 5D Scorecard Test (Hybrid Claim-Based)")
+    print(f"Base URL             : {BASE_URL}")
+    print(f"Strict Nemotron      : {STRICT_COACHING}")
+    print()
+
+    # -------------------------------------------------------------------------
+    # Step 0: Start session
+    # -------------------------------------------------------------------------
+    print("Step 0: POST /api/start-session")
+    try:
+        start = post("/api/start-session", {
+            "mode": "pitch_battle",
+            "startup": SAMPLE_STARTUP,
+            "persona": "hackathon_judge",
+            "difficulty": "high",
+            "input_mode": "text",
+            "model_mode": "premium_nvidia",
+        })
+    except Exception as exc:
+        print(f"  FAIL  Could not start session: {exc}")
+        sys.exit(1)
+
+    session_id = start.get("session_id")
+    check("session_id present", bool(session_id))
+    check("ai_message non-empty", bool(start.get("ai_message")))
+    print(f"  session_id  : {session_id}")
+    print(f"  attack_tag  : {start.get('attack_tag')}")
+    print(f"  ai_message  : {start.get('ai_message', '')[:100]}...\n")
+
+    # -------------------------------------------------------------------------
+    # Steps 1-N: Send answers
+    # -------------------------------------------------------------------------
+    for i, answer in enumerate(ANSWERS):
+        print(f"Step {i + 1}: POST /api/chat-round  answer={answer[:60]!r}")
+        try:
+            data = post("/api/chat-round", {
+                "session_id": session_id,
+                "user_message": answer,
+            })
+        except Exception as exc:
+            print(f"  FAIL  chat-round failed: {exc}")
+            sys.exit(1)
+
+        check("session_id echoed", data.get("session_id") == session_id)
+        check("ai_message non-empty", bool(data.get("ai_message")))
+        print(
+            f"  round={data.get('round')}  "
+            f"quality={data.get('answer_quality')}  "
+            f"action={data.get('judge_action')}  "
+            f"tag={data.get('attack_tag')}\n"
+        )
+
+    # -------------------------------------------------------------------------
+    # Final: POST /api/end-battle
+    # -------------------------------------------------------------------------
+    print("Final step: POST /api/end-battle  (local scoring is fast; Nemotron coaching may take ~60s)")
+    try:
+        sc = post("/api/end-battle", {"session_id": session_id}, timeout=180)
+    except Exception as exc:
+        print(f"  FAIL  end-battle request failed: {exc}")
+        sys.exit(1)
+
+    # --- Top-level required fields ---
+    check("overall present", "overall" in sc, f"keys={list(sc.keys())}")
+    check("overall_label present", "overall_label" in sc)
+    check("scores present", "scores" in sc)
+    check("best_answer present", "best_answer" in sc)
+    check("weakest_answer present", "weakest_answer" in sc)
+    check("improved_answer present", "improved_answer" in sc)
+    check("improved_pitch present", "improved_pitch" in sc)
+    check("top_3_questions present", "top_3_questions" in sc)
+    check("model_ok present", "model_ok" in sc)
+    check("provider present", "provider" in sc)
+    check("scorecard_source present", "scorecard_source" in sc)
+    check("no error key", "error" not in sc, f"error={sc.get('error')}")
+
+    overall = sc.get("overall", -1)
+    check("overall is int 0-100", isinstance(overall, int) and 0 <= overall <= 100, f"got {overall!r}")
+    check(
+        "overall_label valid",
+        sc.get("overall_label") in _VALID_LABELS,
+        f"got {sc.get('overall_label')!r}",
+    )
+
+    # --- concrete_signals_summary ---
+    css = sc.get("concrete_signals_summary")
+    check("concrete_signals_summary present", isinstance(css, dict), f"got {type(css).__name__}")
+    if isinstance(css, dict):
+        for key in ("numbers", "validation", "competitors", "revenue_signals", "technical_mechanisms"):
+            check(
+                f"concrete_signals_summary.{key} is list",
+                isinstance(css.get(key), list),
+                f"got {type(css.get(key)).__name__}",
+            )
+
+    # --- Dimension checks ---
+    scores = sc.get("scores", {})
+    check("all 6 dimensions present", REQUIRED_DIMS <= set(scores.keys()),
+          f"missing={REQUIRED_DIMS - set(scores.keys())}")
+
+    for dim in REQUIRED_DIMS:
+        dim_data = scores.get(dim, {})
+        dim_score = dim_data.get("score", -1)
+        check(
+            f"{dim}.score is int 0-100",
+            isinstance(dim_score, int) and 0 <= dim_score <= 100,
+            f"got {dim_score!r}",
+        )
+        check(f"{dim}.reason non-empty", bool(dim_data.get("reason")))
+        check(
+            f"{dim}.label is valid",
+            dim_data.get("label") in _VALID_LABELS,
+            f"got {dim_data.get('label')!r}",
+        )
+        check(
+            f"{dim}.signals_used is list",
+            isinstance(dim_data.get("signals_used", []), list),
+        )
+
+    # --- top_3_questions ---
+    top3 = sc.get("top_3_questions", [])
+    check("top_3_questions is list", isinstance(top3, list))
+    check("top_3_questions has exactly 3", len(top3) == 3, f"got {len(top3)}")
+    for q in top3:
+        check("question is non-empty string", isinstance(q, str) and bool(q.strip()))
+
+    # --- Source and provider checks (Phase 5D: hybrid architecture) ---
+    source = sc.get("scorecard_source", "")
+    model_ok = sc.get("model_ok")
+    provider = sc.get("provider", "")
+
+    check(
+        "scorecard_source is hybrid",
+        source in _VALID_SOURCES,
+        f"got {source!r} — expected one of {_VALID_SOURCES}",
+    )
+    check(
+        "provider is local or local+nvidia",
+        provider in _VALID_PROVIDERS,
+        f"got {provider!r}",
+    )
+    check("model_ok is bool", isinstance(model_ok, bool), f"got {type(model_ok).__name__}")
+
+    if STRICT_COACHING and source != "hybrid_claims_nemotron":
+        print(
+            f"\n  FAIL  STRICT_NEMOTRON_COACHING=true but source={source!r}\n"
+            f"  model_error: {sc.get('model_error', 'none')}\n"
+            "  Nemotron coaching did not produce valid JSON."
+        )
+        sys.exit(1)
+    elif source == "hybrid_claims_local":
+        print(f"  NOTE: hybrid_claims_local — Nemotron coaching unavailable, local fallback used.")
+        print(f"  model_error: {sc.get('model_error', 'none')}")
+    else:
+        print(f"  NOTE: hybrid_claims_nemotron — Nemotron coaching succeeded.")
+
+    # --- Evidence detection: "50 beta users" should appear in signals/scores ---
+    evidence_terms = ["50 beta", "campus ambassador", "event-miss report", "validated", "beta users"]
+    evidence_fields = [
+        str(sc.get("best_answer", "")),
+        str(sc.get("improved_answer", "")),
+        str(sc.get("improved_pitch", "")),
+    ]
+    for dim in REQUIRED_DIMS:
+        evidence_fields.append(str(scores.get(dim, {}).get("reason", "")))
+        for sig in scores.get(dim, {}).get("signals_used", []):
+            evidence_fields.append(str(sig))
+    if isinstance(css, dict):
+        for key in ("numbers", "validation"):
+            evidence_fields.extend(str(x) for x in css.get(key, []))
+    combined = " ".join(evidence_fields).lower()
+    evidence_found = any(t.lower() in combined for t in evidence_terms)
+    if evidence_found:
+        print("  PASS  Scorecard acknowledges concrete validation evidence from STRONG_ANSWER")
+    else:
+        print("  NOTE  Scorecard did not explicitly reference validation evidence (not a hard fail in 5D)")
+
+    # --- No static EventRadar mock content ---
+    all_text = " ".join([
+        str(sc.get("best_answer", "")),
+        str(sc.get("weakest_answer", "")),
+        str(sc.get("improved_answer", "")),
+        str(sc.get("improved_pitch", "")),
+    ])
+    check(
+        "no static WhatsApp groups mock content",
+        "WhatsApp groups" not in all_text or "EventRadar" in SAMPLE_STARTUP.get("name", ""),
+    )
+
+    # --- Leakage check ---
+    scorecard_text = " ".join([
+        str(sc.get("best_answer", "")),
+        str(sc.get("weakest_answer", "")),
+        str(sc.get("improved_answer", "")),
+        str(sc.get("improved_pitch", "")),
+        str(sc.get("why_weak", "")),
+    ])
+    check("no leakage in scorecard text", not _LEAKAGE.search(scorecard_text), "instruction leakage detected")
+
+    # -------------------------------------------------------------------------
+    # Summary
+    # -------------------------------------------------------------------------
+    print("\n--- Scorecard Summary ---")
+    print(f"  scorecard_source : {sc.get('scorecard_source')}")
+    print(f"  model_ok         : {sc.get('model_ok')}  provider: {sc.get('provider')}")
+    print(f"  overall          : {overall}  ({sc.get('overall_label')})")
+    print()
+    for dim in REQUIRED_DIMS:
+        d = scores.get(dim, {})
+        sigs = d.get("signals_used", [])
+        print(
+            f"  {dim:<25}  score={d.get('score', '?'):>3}  [{d.get('label', '?')}]"
+            + (f"  sigs={sigs[:2]}" if sigs else "")
+        )
+    print()
+    print(f"  weakest_answer   : {sc.get('weakest_answer', '')[:120]}")
+    print(f"  improved_answer  : {sc.get('improved_answer', '')[:120]}")
+    print(f"  top_3_questions  :")
+    for q in top3:
+        print(f"    - {q}")
+    if isinstance(css, dict):
+        print(f"\n  concrete_signals_summary:")
+        for k, v in css.items():
+            if v:
+                print(f"    {k}: {v[:3]}")
+
+    if sc.get("model_error"):
+        print(f"\n  model_error : {sc.get('model_error')}")
+
+    print("\nAll Phase 5D scorecard checks passed.\n")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_phase5b_refinement.py

@@ -0,0 +1,240 @@
+"""Phase 5B/5D refinement test: 8+ rounds, soft limit, battle_phase, labels, no leakage.
+
+Validates:
+  - User can continue chatting past MAX_ROUNDS (no hard block)
+  - soft_round_limit_reached appears at round >= MAX_ROUNDS
+  - battle_phase progresses: explore (1-3), pressure (4-6), close (7+)
+  - No instruction leakage in any ai_message
+  - /api/end-battle returns hybrid claim-based scorecard with score labels
+  - overall_label and per-dimension labels present
+  - scorecard_source in ("hybrid_claims_nemotron", "hybrid_claims_local")
+
+Usage:
+  python scripts/test_phase5b_refinement.py
+  ALLOW_SCORECARD_FALLBACK=true python scripts/test_phase5b_refinement.py
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+import requests
+
+BASE_URL = os.getenv("PITCHFIGHT_BASE_URL", "http://127.0.0.1:7861").rstrip("/")
+ALLOW_FALLBACK = os.getenv("ALLOW_SCORECARD_FALLBACK", "false").strip().lower() == "true"
+MAX_ROUNDS = int(os.getenv("MAX_ROUNDS", "6"))
+
+SAMPLE_STARTUP = {
+    "name": "EventRadar AI",
+    "problem": "Students miss relevant hackathons, workshops, and networking events.",
+    "solution": "AI-powered event discovery that ranks events by fit for each student profile.",
+    "why_ai": "Personalized ranking requires understanding student goals and event signals together.",
+    "stage": "Prototype",
+    "team": "2 founders",
+    "traction": "50 beta signups, no revenue yet",
+}
+
+STRONG_ANSWER = (
+    "We validated this with 50 beta users, 3 campus ambassadors, "
+    "and weekly event-miss reports from two colleges."
+)
+
+# 9 answers to go well past MAX_ROUNDS=6
+ANSWERS = [
+    "It is a pretty big market because students attend events often.",         # weak
+    "I don't know",                                                             # non_answer
+    STRONG_ANSWER,                                                              # strong
+    "The AI ranks events based on student interest profiles.",                  # partial
+    "We use embeddings and a ranking model trained on student behavior data.",  # strong
+    "okay",                                                                     # non_answer
+    "Our differentiation is the personalization layer no event aggregator has.",# partial
+    "We plan to charge colleges $500/month for analytics and promotions.",      # partial (revenue)
+    "We have 3 campus ambassadors onboarding 20 students each right now.",      # strong
+]
+
+REQUIRED_DIMS = {
+    "clarity", "problem_understanding", "market_awareness",
+    "differentiation", "business_model", "objection_handling",
+}
+_VALID_LABELS = {"Not addressed", "Developing", "Solid", "Strong", "Excellent"}
+
+_LEAKAGE = re.compile(
+    r"we need to\b|the prompt says\b|as instructed\b|my instructions\b"
+    r"|i am supposed to\b|i should follow\b|the rules say\b|per the instructions?\b",
+    re.IGNORECASE,
+)
+
+
+def post(path: str, body: dict, timeout: int = 180) -> dict:
+    resp = requests.post(f"{BASE_URL}{path}", json=body, timeout=timeout)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    marker = "PASS" if condition else "FAIL"
+    suffix = f" — {detail}" if detail else ""
+    print(f"  {marker}  {label}{suffix}")
+    if not condition:
+        sys.exit(1)
+
+
+def main() -> None:
+    print(f"\nPhase 5B Refinement Test")
+    print(f"Base URL       : {BASE_URL}")
+    print(f"MAX_ROUNDS     : {MAX_ROUNDS}")
+    print(f"Allow fallback : {ALLOW_FALLBACK}")
+    print(f"Total answers  : {len(ANSWERS)} (well past MAX_ROUNDS)\n")
+
+    # -------------------------------------------------------------------------
+    # Step 0: Start session
+    # -------------------------------------------------------------------------
+    print("Step 0: POST /api/start-session")
+    try:
+        start = post("/api/start-session", {
+            "mode": "pitch_battle",
+            "startup": SAMPLE_STARTUP,
+            "persona": "hackathon_judge",
+            "difficulty": "high",
+            "input_mode": "text",
+            "model_mode": "premium_nvidia",
+        })
+    except Exception as exc:
+        print(f"  FAIL  Could not start session: {exc}")
+        sys.exit(1)
+
+    session_id = start.get("session_id")
+    check("session_id present", bool(session_id))
+    check("ai_message non-empty", bool(start.get("ai_message")))
+    check("battle_complete=False at start", start.get("battle_complete") is False)
+    check("can_continue=True at start", start.get("can_continue") is True)
+    check("battle_phase present", bool(start.get("battle_phase")))
+    check("start battle_phase=explore", start.get("battle_phase") == "explore",
+          f"got {start.get('battle_phase')!r}")
+    check("no leakage in opening", not _LEAKAGE.search(start.get("ai_message", "")))
+
+    print(f"  session_id   : {session_id}")
+    print(f"  attack_tag   : {start.get('attack_tag')}")
+    print(f"  battle_phase : {start.get('battle_phase')}")
+    print(f"  ai_message   : {start.get('ai_message', '')[:100]}...\n")
+
+    # -------------------------------------------------------------------------
+    # Steps 1..len(ANSWERS): send all answers, including past MAX_ROUNDS
+    # -------------------------------------------------------------------------
+    soft_limit_seen = False
+
+    for i, answer in enumerate(ANSWERS):
+        print(f"Step {i + 1}: POST /api/chat-round  answer={answer[:60]!r}")
+        try:
+            data = post("/api/chat-round", {"session_id": session_id, "user_message": answer})
+        except Exception as exc:
+            print(f"  FAIL  chat-round failed: {exc}")
+            sys.exit(1)
+
+        rnd   = data.get("round", 0)
+        phase = data.get("battle_phase", "")
+        sl    = data.get("soft_round_limit_reached", False)
+        bc    = data.get("battle_complete", True)
+        cc    = data.get("can_continue", False)
+        na    = data.get("next_action", "")
+        ai    = data.get("ai_message", "")
+
+        print(f"  round={rnd}  phase={phase}  soft_limit={sl}  "
+              f"battle_complete={bc}  can_continue={cc}")
+        print(f"  ai_message: {ai[:100]}...\n")
+
+        # Always must continue
+        check("battle_complete=False (never hard-stopped)", bc is False, f"round={rnd}")
+        check("can_continue=True (always)", cc is True, f"round={rnd}")
+        check("next_action=continue (always)", na == "continue", f"got {na!r}")
+        check("ai_message non-empty", bool(ai))
+        check("no leakage in ai_message", not _LEAKAGE.search(ai),
+              f"leakage at round {rnd}")
+
+        # Soft limit
+        if rnd >= MAX_ROUNDS:
+            check("soft_round_limit_reached=True", sl is True, f"round={rnd}")
+            if sl:
+                soft_limit_seen = True
+        else:
+            check("soft_round_limit_reached=False", sl is False, f"round={rnd}")
+
+        # Battle phase progression
+        if 1 <= rnd <= 3:
+            check(f"phase=explore at round {rnd}", phase == "explore", f"got {phase!r}")
+        elif 4 <= rnd <= 6:
+            check(f"phase=pressure at round {rnd}", phase == "pressure", f"got {phase!r}")
+        elif rnd >= 7:
+            check(f"phase=close at round {rnd}", phase == "close", f"got {phase!r}")
+
+    check("soft_round_limit_reached appeared at least once", soft_limit_seen)
+
+    # -------------------------------------------------------------------------
+    # Final: POST /api/end-battle
+    # -------------------------------------------------------------------------
+    print(f"\nFinal: POST /api/end-battle (may take up to 3 minutes)")
+    try:
+        sc = post("/api/end-battle", {"session_id": session_id}, timeout=240)
+    except Exception as exc:
+        print(f"  FAIL  end-battle failed: {exc}")
+        sys.exit(1)
+
+    # Top-level fields
+    check("overall present", "overall" in sc)
+    check("overall_label present", "overall_label" in sc)
+    check("scores present", "scores" in sc)
+    check("scorecard_source present", "scorecard_source" in sc)
+    check("model_ok present", "model_ok" in sc)
+
+    overall = sc.get("overall", -1)
+    check("overall 0-100", isinstance(overall, int) and 0 <= overall <= 100, f"got {overall!r}")
+    check(
+        "overall_label valid",
+        sc.get("overall_label") in _VALID_LABELS,
+        f"got {sc.get('overall_label')!r}",
+    )
+
+    # Dimension labels
+    scores = sc.get("scores", {})
+    check("all 6 dims present", REQUIRED_DIMS <= set(scores.keys()))
+    for dim in REQUIRED_DIMS:
+        d = scores.get(dim, {})
+        check(f"{dim}.label valid", d.get("label") in _VALID_LABELS, f"got {d.get('label')!r}")
+        dim_score = d.get("score", -1)
+        check(f"{dim}.score 0-100", isinstance(dim_score, int) and 0 <= dim_score <= 100)
+
+    # Scorecard source check (Phase 5D: hybrid architecture)
+    source = sc.get("scorecard_source", "")
+    _hybrid_sources = {"hybrid_claims_nemotron", "hybrid_claims_local"}
+    check(
+        "scorecard_source is hybrid",
+        source in _hybrid_sources,
+        f"got {source!r} — expected one of {_hybrid_sources}",
+    )
+    check(
+        "provider is local or local+nvidia",
+        sc.get("provider") in {"local+nvidia", "local"},
+        f"got {sc.get('provider')!r}",
+    )
+    if source == "hybrid_claims_local":
+        print(f"  NOTE: hybrid_claims_local — Nemotron coaching unavailable, local fallback used.")
+        if sc.get("model_error"):
+            print(f"  model_error: {sc.get('model_error')}")
+    else:
+        print("  NOTE: hybrid_claims_nemotron — Nemotron coaching succeeded.")
+
+    print(f"\n--- Refinement Summary ---")
+    print(f"  scorecard_source : {sc.get('scorecard_source')}")
+    print(f"  overall          : {overall}  ({sc.get('overall_label')})")
+    for dim in REQUIRED_DIMS:
+        d = scores.get(dim, {})
+        print(f"  {dim:<25}  {d.get('score', '?'):>3}  [{d.get('label', '?')}]")
+
+    print("\nAll Phase 5B refinement checks passed.\n")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()